[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93083":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},93083,"browser-mcp","MoisesR7\u002Fbrowser-mcp","MoisesR7","browser mcp agent integration with autonomous browser automation capabilities","",null,"TypeScript",135,695,51,0,102,58.53,"Mozilla Public License 2.0",false,"main",true,[23,5,24],"browser","mcp","2026-07-22 04:02:08","# MCP Browser Agent\n\n[![Trust Score](https:\u002F\u002Farchestra.ai\u002Fmcp-catalog\u002Fapi\u002Fbadge\u002Fquality\u002Fimprvhub\u002Fmcp-browser-agent)](https:\u002F\u002Farchestra.ai\u002Fmcp-catalog\u002Fimprvhub__mcp-browser-agent)\n[![smithery badge](https:\u002F\u002Fsmithery.ai\u002Fbadge\u002F@imprvhub\u002Fmcp-browser-agent)](https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@imprvhub\u002Fmcp-browser-agent)\n\n\u003Ctable style=\"border-collapse: collapse; width: 100%; table-layout: fixed;\">\n\u003Ctr>\n\u003Ctd style=\"width: 40%; padding: 15px; vertical-align: middle; border: none;\">A powerful Model Context Protocol (MCP) integration that provides Claude Desktop with autonomous browser automation capabilities.\u003C\u002Ftd>\n\u003Ctd style=\"width: 60%; padding: 0; vertical-align: middle; border: none; min-width: 300px; text-align: center;\">\u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002F@imprvhub\u002Fmcp-browser-agent\">\n  \u003Cimg style=\"max-width: 100%; height: auto; min-width: 300px;\" src=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002F@imprvhub\u002Fmcp-browser-agent\u002Fbadge\" alt=\"Browser Agent MCP server\" \u002F>\n\u003C\u002Fa>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n## Features\n\n- **Advanced Browser Automation**\n  - Navigate to any URL with customizable load strategies\n  - Capture full-page or element-specific screenshots\n  - Perform precise DOM interactions (click, fill, select, hover)\n  - Execute arbitrary JavaScript in browser context with console logs capture\n\n- **Powerful API Client**\n  - Execute HTTP requests (GET, POST, PUT, PATCH, DELETE)\n  - Configure request headers and body content\n  - Process response data with JSON formatting\n  - Error handling with detailed feedback\n\n- **MCP Resource Management**\n  - Access browser console logs as resources\n  - Retrieve screenshots through MCP resource interface\n  - Persistent session with headful browser instance\n\n- **AI Agent Capabilities**\n  - Chain multiple browser operations for complex tasks\n  - Follow multi-step instructions with intelligent error recovery\n  - Technical task automation through natural language instructions\n\n## Demo\n\n\u003Cp>\n  \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE\">\n    \u003Cimg src=\"public\u002Fassets\u002Fpreview.png\" width=\"600\" alt=\"Browser Agent MCP server demo\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cdetails>\n\u003Csummary> Timestamps: \u003C\u002Fsummary>\n\nClick on any timestamp to jump to that section of the video\n\n[**00:00**](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE&t=0s) - **Google Search for MCP**  \nNavigation to Google homepage and search for \"Model Context Protocol\". Demonstration of Claude Desktop using the MCP integration to perform a basic web search and process the results.\n\n[**00:33**](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE&t=33s) - **Screenshot Capture**  \nTaking a screenshot of the search results with a custom filename and showcasing it in Finder. Shows how Claude can capture and save visual content from web pages during browser automation.\n\n[**01:00**](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE&t=60s) - **Wikipedia Search**  \nNavigation to Wikipedia.org and search for \"Model Context Protocol\". Illustrates Claude's ability to interact with different websites and their search functionality through the MCP integration.\n\n[**01:38**](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE&t=98s) - **Dropdown Menu Interaction I**  \nNavigation to a test website (the-internet.herokuapp.com\u002Fdropdown) and selection of \"Option 1\" from a dropdown menu. Demonstrates Claude's capability to interact with form elements and make selections.\n\n[**01:56**](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE&t=116s) - **Dropdown Menu Interaction II**  \nChanging the selection to \"Option 2\" from the same dropdown menu. Shows Claude's ability to manipulate the same form element multiple times and make different selections.\n\n[**02:09**](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE&t=129s) - **Login Form Completion**  \nNavigation to a login page (the-internet.herokuapp.com\u002Flogin) and filling in the username field with \"tomsmith\" and password field with \"SuperSecretPassword!\". Demonstrates form filling automation.\n\n[**02:28**](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE&t=148s) - **Login Submission**  \nSubmitting the login credentials and completing the authentication process. Shows Claude's ability to trigger form submissions and navigate through multi-step processes.\n\n[**02:36**](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0lMsKiTy7TE&t=156s) - **API Request Execution**  \nPerforming a GET request to JSONPlaceholder API endpoint. Demonstrates Claude's capability to make direct API calls and process the returned data through the MCP integration.\n\u003C\u002Fdetails>\n\n## Requirements\n\n- Node.js 16 or higher\n- Claude Desktop\n- Playwright dependencies\n\n### Browser Support\n\n```bash\nnpm init playwright@latest\n```\n\nThis package includes Playwright and the necessary dependencies for running browser automation. When you run `npm install`, the required Playwright dependencies will be installed. The package supports the following browsers:\n\n- Chrome (default)\n- Firefox\n- Microsoft Edge\n- WebKit (Safari engine)\n\nWhen you first use a browser type, Playwright will automatically install the corresponding browser drivers as needed. You can also install them manually with the following commands:\n\n```\nnpx playwright install chrome\nnpx playwright install firefox\nnpx playwright install webkit\nnpx playwright install msedge\n```\n\n> **Note about Safari**: Playwright doesn't provide direct support for Safari browser. Instead, it uses WebKit, which is the browser engine that powers Safari.\n>\n> **Note about Edge**: When selecting Edge as the browser type, the agent will actually launch Microsoft Edge (not Chromium). Technically, in Playwright, Edge is launched using the Chromium browser instance with the 'msedge' channel parameter because Microsoft Edge is based on Chromium.\n## Installation\n\n### Installing Manually\n1. Clone or download this repository:\n```\ngit clone https:\u002F\u002Fgithub.com\u002FMoisesR7\u002Fbrowser-mcp\ncd browser-mcp\n```\n\n2. Install dependencies:\n```\nnpm install\n```\n\n### Redis (optional)\n\nRedis caches `api_get` responses and rate-limits API tools per host when `REDIS_URL` is set:\n\n```bash\ndocker compose up -d redis\ncp .env.example .env\n```\n\n| Feature | Behavior |\n|---------|----------|\n| `api_get` | 60 second response cache |\n| API tools | 60 requests\u002Fminute per host |\n| `health_check` | Reports Redis connectivity |\n\nWithout `REDIS_URL`, all tools work normally and skip caching\u002Frate limits.\n\n3. Build the project:\n```\nnpm run build\n```\n\n## Running the MCP Server\n\nThere are two ways to run the MCP server:\n\n### Option 1: Running manually\n\n1. Open a terminal or command prompt\n2. Navigate to the project directory\n3. Run the server directly:\n\n```\nnode dist\u002Findex.js\n```\n\nKeep this terminal window open while using Claude Desktop. The server will run until you close the terminal.\n\n### Option 2: Auto-starting with Claude Desktop (recommended for regular use)\n\nThe Claude Desktop can automatically start the MCP server when needed. To set this up:\n\n#### Configuration\n\nThe Claude Desktop configuration file is located at:\n\n- **macOS**: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~\u002F.config\u002FClaude\u002Fclaude_desktop_config.json`\n\nEdit this file to add the Browser Agent MCP configuration. If the file doesn't exist, create it:\n\n```json\n{\n  \"mcpServers\": {\n    \"browserAgent\": {\n      \"command\": \"node\",\n      \"args\": [\"ABSOLUTE_PATH_TO_DIRECTORY\u002Fmcp-browser-agent\u002Fdist\u002Findex.js\",\n      \"--browser\",\n      \"chrome\"\n    ]\n    }\n  }\n}\n```\n\n**Important**: Replace `ABSOLUTE_PATH_TO_DIRECTORY` with the **complete absolute path** where you installed the MCP\n  - macOS\u002FLinux example: `\u002FUsers\u002Fusername\u002Fmcp-browser-agent`\n  - Windows example: `C:\\\\Users\\\\username\\\\mcp-browser-agent`\n\nIf you already have other MCPs configured, simply add the \"browserAgent\" section inside the \"mcpServers\" object. Here's an example of a configuration with multiple MCPs:\n\n```json\n{\n  \"mcpServers\": {\n    \"otherMcp1\": {\n      \"command\": \"...\",\n      \"args\": [\"...\"]\n    },\n    \"otherMcp2\": {\n      \"command\": \"...\",\n      \"args\": [\"...\"]\n    },\n    \"browserAgent\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"ABSOLUTE_PATH_TO_DIRECTORY\u002Fmcp-browser-agent\u002Fdist\u002Findex.js\",\n      \"--browser\",\n      \"chrome\"\n    ]\n    }\n  }\n}\n```\n\n## Browser Selection\n\nThe MCP Browser Agent supports multiple browser types. By default, it uses Chrome, but you can specify a different browser in several ways:\n\n### Option 1: Configuration File\n\nCreate or edit the file `.mcp_browser_agent_config.json` in your home directory:\n\n```json\n{\n  \"browserType\": \"chrome\"\n}\n```\n\nSupported values for `browserType` are:\n- `chrome` - Uses installed Chrome (default)\n- `firefox` - Uses Firefox 'Nightly' browser\n- `webkit` - Uses WebKit engine (Note: This is not Safari itself but the WebKit rendering engine that powers Safari)\n- `edge` - Uses Microsoft Edge\n\n> **Note about Safari**: Playwright doesn't provide direct support for Safari browser. Instead, it uses WebKit, which is the browser engine that powers Safari. The WebKit implementation in Playwright provides similar functionality but is not identical to the Safari browser experience.\n\n### Option 2: Command Line Argument\n\nWhen starting the MCP server manually, you can specify the browser type:\n\n```\nnode dist\u002Findex.js --browser firefox\n```\n\n### Option 3: Environment Variable\n\nSet the `MCP_BROWSER_TYPE` environment variable:\n\n```\nMCP_BROWSER_TYPE=firefox node dist\u002Findex.js\n```\n\n### Option 4: Claude Desktop Configuration\n\nWhen configuring the MCP in Claude Desktop's `claude_desktop_config.json`, you can specify the browser type:\n\n```json\n{\n  \"mcpServers\": {\n    \"browserAgent\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"ABSOLUTE_PATH_TO_DIRECTORY\u002Fmcp-browser-agent\u002Fdist\u002Findex.js\",\n        \"--browser\",\n        \"chrome\"\n      ]\n    }\n  }\n}\n```\n\n## Technical Implementation\n\nMCP Browser Agent is built on the Model Context Protocol, enabling Claude to interact with a headful browser through Playwright. The implementation consists of four main components:\n\n1. **Server (index.ts)**\n   - Initializes the MCP server with Model Context Protocol standard protocol\n   - Configures server capabilities for tools and resources\n   - Establishes communication with Claude through the stdio transport\n\n2. **Tools Registry (tools.ts)**\n   - Defines browser and API tool schemas\n   - Specifies parameters, validation rules, and descriptions\n   - Registers tools with the MCP server for Claude's discovery\n\n3. **Request Handlers (handlers.ts)**\n   - Manages MCP protocol requests for tools and resources\n   - Exposes browser logs and screenshots as queryable resources\n   - Routes tool execution requests to the appropriate handlers\n\n4. **Executor (executor.ts)**\n   - Manages browser and API client lifecycle\n   - Implements browser automation functions using Playwright\n   - Handles API requests with proper error handling and response parsing\n   - Maintains stateful browser session between commands\n\n### Agent Capabilities\n\nUnlike basic integrations, MCP Browser Agent functions as a true AI agent by:\n\n- Maintaining persistent browser state across multiple commands\n- Capturing detailed console logs for debugging\n- Storing screenshots for reference and review\n- Managing complex interaction sequences\n- Providing detailed error information for recovery\n- Supporting chained operations for complex workflows\n\n## Available Tools\n\n### Browser Tools\n\n| Tool Name | Description | Parameters |\n|-----------|-------------|------------|\n| `browser_navigate` | Navigate to a URL | `url` (required), `timeout`, `waitUntil` |\n| `browser_screenshot` | Capture screenshot | `name` (required), `selector`, `fullPage`, `mask`, `savePath` |\n| `browser_click` | Click element | `selector` (required) |\n| `browser_fill` | Fill form input | `selector` (required), `value` (required) |\n| `browser_select` | Select dropdown option | `selector` (required), `value` (required) |\n| `browser_hover` | Hover over element | `selector` (required) |\n| `browser_evaluate` | Execute JavaScript | `script` (required) |\n\n### API Tools\n\n| Tool Name | Description | Parameters |\n|-----------|-------------|------------|\n| `api_get` | GET request | `url` (required), `headers` |\n| `api_post` | POST request | `url` (required), `data` (required), `headers` |\n| `api_put` | PUT request | `url` (required), `data` (required), `headers` |\n| `api_patch` | PATCH request | `url` (required), `data` (required), `headers` |\n| `api_delete` | DELETE request | `url` (required), `headers` |\n\n## Resource Access\n\nThe MCP Browser Agent exposes the following resources:\n\n- `browser:\u002F\u002Flogs` - Access browser console logs\n- `screenshot:\u002F\u002F[name]` - Access screenshots by name\n\n\n## Example Usage\n\nHere are some realistic examples of how to use the MCP Browser Agent with Claude:\n\n### Basic Browser Navigation\n\n```\nNavigate to the Google homepage at https:\u002F\u002Fwww.google.com\n```\n\n```\nTake a screenshot of the current page and name it \"google-homepage\"\n```\n\n```\nType \"weather forecast\" in the search box\n```\n\n### Simple Interactions\n\n```\nNavigate to https:\u002F\u002Fwww.wikipedia.org and search for \"Model Context Protocol\"\n```\n\n```\nGo to https:\u002F\u002Fthe-internet.herokuapp.com\u002Fdropdown and select the option \"Option 1\" from the dropdown\n```\n\n### Basic Form Filling\n\n```\nNavigate to https:\u002F\u002Fthe-internet.herokuapp.com\u002Flogin and fill in the username field with \"tomsmith\" and the password field with \"SuperSecretPassword!\"\n```\n\n```\nGo to https:\u002F\u002Fthe-internet.herokuapp.com\u002Flogin, fill in the username and password fields, then click the login button\n```\n\n### Simple JavaScript Execution\n\n```\nGo to https:\u002F\u002Fexample.com and execute a JavaScript script to return the page title\n```\n\n```\nNavigate to https:\u002F\u002Fwww.google.com and execute a JavaScript script to count the number of links on the page\n```\n\n### Basic API Requests\n\n```\nPerform a GET request to https:\u002F\u002Fjsonplaceholder.typicode.com\u002Ftodos\u002F1\n```\n\n```\nMake a POST request to https:\u002F\u002Fjsonplaceholder.typicode.com\u002Fposts with appropriate JSON data\n```\n\nThese examples represent the actual capabilities of the MCP Browser Agent and are more realistic about what it can accomplish in its current state.\n\n## Troubleshooting\n\n### \"Server disconnected\" error\nIf you see the error \"MCP Browser Agent: Server disconnected\" in Claude Desktop:\n\n1. **Verify the server is running**:\n   - Open a terminal and manually run `node dist\u002Findex.js` from the project directory\n   - If the server starts successfully, use Claude while keeping this terminal open\n\n2. **Check your configuration**:\n   - Ensure the absolute path in `claude_desktop_config.json` is correct for your system\n   - Double-check that you've used double backslashes (`\\\\`) for Windows paths\n   - Verify you're using the complete path from the root of your filesystem\n\n### Browser not appearing\nIf the browser doesn't launch or you don't see it:\n\n1. **Check if the specified browser is installed**\n   - Verify that you have the browser (Chrome, Firefox, Edge, or Safari\u002FWebKit) installed on your system\n   - The browser drivers are handled automatically by Playwright\n\n2. **Restart the server and Claude Desktop**\n   - Kill any existing node processes that might be running the server\n   - Restart Claude Desktop to establish a fresh connection\n\n### Browser process not closing properly\nThere are known issues with Chromium and Chrome browsers where the process sometimes doesn't terminate properly after use. If you experience this issue:\n\n1. **Manually close the browser process**:\n   - **Windows**: Press Ctrl+Shift+Esc to open Task Manager, find the Chrome\u002FChromium process and end it\n   - **macOS**: Open Activity Monitor (Applications > Utilities > Activity Monitor), find the Chrome\u002FChromium process and click the X to terminate it\n   - **Linux**: Run `ps aux | grep chrome` or `ps aux | grep chromium` to find the process, then `kill \u003CPID>` to terminate it\n\n2. **Note about browser compatibility**:\n   - This issue has been observed primarily with Chromium and Chrome\n   - Firefox and Playwright's built-in browser don't typically experience this problem\n\n> [!CAUTION]\n> This MCP integration is built on Playwright, which has known issues and bugs that may affect its operation. Please report any issues you encounter with the browser automation to [Playwright's GitHub issues](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fplaywright\u002Fissues). The Playwright team is continuously working to address these issues, but this agent provides a foundation for browser automation capabilities with Claude Desktop despite these limitations.\n\n## Development\n\n### Project Structure\n\n- `src\u002Findex.ts`: Main entry point and MCP server initialization\n- `src\u002Ftools.ts`: Tool schemas and registration\n- `src\u002Fhandlers.ts`: MCP request handlers for tools and resources\n- `src\u002Fexecutor.ts`: Tool implementation logic using Playwright\n\n### Building\n\n```\nnpm run build\n```\n\n### Watching for Changes\n\n```\nnpm run watch\n```\n\n## Testing\n\nThe project includes tests to verify core functionality and browser handling.\n\n```\nnpm test               # Run tests\nnpm run test:watch     # Watch mode\nnpm run test:coverage  # Coverage report\n```\n\nTests verify configuration integrity, browser automation features, error handling, and process cleanup. The test suite focuses particularly on ensuring proper handling of browser processes due to known issues with Chrome\u002FChromium termination.\n\n## Security Considerations\n\n> [!IMPORTANT]\n> This MCP integration provides Claude with autonomous browser control capabilities. Please review our [Security Policy](SECURITY.md) for important information about prohibited uses, security implications, and best practices.\n\nThe MCP Browser Agent is designed for legitimate automation tasks but could potentially be misused. Users are responsible for ensuring their use complies with all applicable laws, terms of service, and ethical guidelines. See our detailed [Security Policy](SECURITY.md) for more information.\n\n## Contributing\n\nContributions to the MCP Browser Agent are welcome! Here are some areas where you can help:\n\n- Adding new browser automation capabilities\n- Improving error handling and recovery\n- Enhancing screenshot and resource management\n- Creating useful workflows and examples\n- Optimizing performance for complex operations\n\n## License\n\nThis project is licensed under the Mozilla Public License 2.0 - see the [LICENSE](https:\u002F\u002Fgithub.com\u002FMoisesR7\u002Fbrowser-mcp\u002Fblob\u002Fmain\u002FLICENSE) file for details.\n\n## Related Links\n\n- [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\n- [Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload)\n- [Playwright Documentation](https:\u002F\u002Fplaywright.dev\u002Fdocs\u002Fintro)\n- [MCP Series](https:\u002F\u002Fgithub.com\u002Fmcp-series)\n","这是一个基于Model Context Protocol（MCP）标准的浏览器自动化代理工具，为AI桌面客户端（如Claude Desktop）提供自主网页操作能力。核心功能包括URL导航、DOM级交互（点击\u002F填表\u002F悬停）、全页或元素截图、浏览器内JavaScript执行与控制台日志捕获，以及HTTP API调用与响应处理；所有操作通过MCP协议标准化暴露，支持资源化访问（如截图、日志）和持久化浏览器会话。适用于需要AI驱动的端到端网页任务自动化场景，例如智能数据采集、跨站表单填写、动态内容验证及MCP生态中的浏览器能力扩展。",2,"2026-07-11 02:30:51","CREATED_QUERY"]