{"id":29975483,"url":"https://github.com/qckfx/browser-ai","last_synced_at":"2026-05-16T17:01:48.489Z","repository":{"id":305842377,"uuid":"1024064663","full_name":"qckfx/browser-ai","owner":"qckfx","description":"AI-powered MCP server that provides natural language control for browser automation. Built on Playwright with an intelligent sub-agent that handles tool orchestration, keeping browser automation details out of Claude's context window. Features OAuth authentication for Claude subscribers and seamless web task automation.","archived":false,"fork":false,"pushed_at":"2025-07-22T07:56:59.000Z","size":53,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-22T09:49:06.725Z","etag":null,"topics":["ai","claude","cursor","playwright","testing"],"latest_commit_sha":null,"homepage":"https://qckfx.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qckfx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-22T06:17:31.000Z","updated_at":"2025-07-22T08:11:24.000Z","dependencies_parsed_at":"2025-07-22T09:49:11.771Z","dependency_job_id":"0916344f-2a42-4807-84f4-55dad8c2e72f","html_url":"https://github.com/qckfx/browser-ai","commit_stats":null,"previous_names":["qckfx/browser-ai"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/qckfx/browser-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qckfx%2Fbrowser-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qckfx%2Fbrowser-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qckfx%2Fbrowser-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qckfx%2Fbrowser-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qckfx","download_url":"https://codeload.github.com/qckfx/browser-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qckfx%2Fbrowser-ai/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268666222,"owners_count":24287181,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-04T02:00:09.867Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","cursor","playwright","testing"],"created_at":"2025-08-04T08:01:37.838Z","updated_at":"2026-05-16T17:01:48.408Z","avatar_url":"https://github.com/qckfx.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Browser AI MCP Server\n\n[![smithery badge](https://smithery.ai/badge/@qckfx/browser-ai)](https://smithery.ai/server/@qckfx/browser-ai)\n\nAn AI-powered MCP (Model Context Protocol) server that provides a natural language interface to browser automation. This server acts as an intelligent wrapper around the official Playwright MCP server, allowing you to control browsers using plain English commands through Claude.\n\n## Features\n\n- **Natural Language Browser Control**: Execute browser automation tasks using plain English commands\n- **Claude Integration**: Leverages Claude's AI capabilities through OAuth (using your Claude Code subscription)\n- **Intelligent Tool Mapping**: AI automatically translates your commands into appropriate Playwright tool calls\n- **Session Management**: Maintain context across multiple browser automation commands\n- **Error Recovery**: Smart error handling with helpful feedback\n\n## Installation\n\n### Installing via Smithery\n\nTo install Browser AI for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@qckfx/browser-ai):\n\n```bash\nnpx -y @smithery/cli install @qckfx/browser-ai --client claude\n```\n\n### Manual Installation\n```bash\nnpm install -g @qckfx/browser-ai\n```\n\nOr use directly with npx:\n\n```bash\nnpx @qckfx/browser-ai\n```\n\n## Setup\n\n### 1. Authentication\n\nThe Browser AI MCP server requires Anthropic API access. You have two authentication options:\n\n#### Option 1: OAuth Authentication (Recommended for Claude Subscribers)\nIf you have a Claude subscription, authenticate with your Claude account to use your subscription credits:\n\n```bash\nnpx @qckfx/browser-ai --auth\n```\n\nThis will open a browser window for OAuth authentication. After authorizing, the token will be saved securely and your API usage will be charged to your Claude subscription rather than requiring separate API credits.\n\n#### Option 2: API Key Authentication\nAlternatively, you can use an Anthropic API key by setting the environment variable:\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-api-key-here\"\n```\n\n### 2. Configure with Claude Code\n\nAfter authentication, add the server to Claude Code:\n\n```bash\nclaude mcp add browser-ai -- npx --yes @qckfx/browser-ai@latest\n```\n\nIf using API key authentication, you can pass it as an environment variable:\n\n```bash\nclaude mcp add browser-ai --env ANTHROPIC_API_KEY=\"your-api-key-here\" -- npx --yes @qckfx/browser-ai@latest\n```\n\n### 3. Configure Claude Desktop (Alternative)\n\nIf using Claude Desktop instead, add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"browser-ai\": {\n      \"command\": \"npx\",\n      \"args\": [\"@qckfx/browser-ai\"],\n      \"env\": {\n        \"PLAYWRIGHT_MCP_PATH\": \"@playwright/mcp@latest\"\n      }\n    }\n  }\n}\n```\n\n## Usage\n\nOnce configured, you can use natural language commands in Claude to control browser automation:\n\n### Example Commands\n\n- **Navigation**: \"Go to example.com and wait for the page to load\"\n- **Clicking**: \"Click the login button\"\n- **Form Filling**: \"Fill the username field with 'john.doe@example.com'\"\n- **Screenshots**: \"Take a screenshot of the current page\"\n- **Complex Tasks**: \"Fill out the registration form with test data and submit it\"\n\n### How It Works\n\n1. You provide a natural language command to Claude\n2. The AI interprets your intent and breaks it down into Playwright tool calls\n3. The server executes these tools via the Playwright MCP server\n4. Results are returned in a user-friendly format\n\n## Development\n\n### Project Structure\n\n```\nbrowser-ai/\n├── src/\n│   ├── auth/          # OAuth authentication\n│   ├── mcp/           # MCP server and client\n│   ├── ai/            # AI agent and tool mapping\n│   ├── provider/      # Custom AI SDK provider\n│   └── index.ts       # CLI entry point\n```\n\n### Building from Source\n\n```bash\ngit clone \u003crepository\u003e\ncd browser-ai\nnpm install\nnpm run build\n```\n\n### Testing\n\nRun the integration test:\n\n```bash\nnpm test\n```\n\n### Debug Mode\n\nEnable debug logging:\n\n```bash\nnpx browser-ai --debug\n```\n\n## Architecture\n\n```\nUser Command → Claude → Browser AI MCP → AI Agent → Playwright MCP → Browser\n                              ↓\n                        Claude (via OAuth)\n```\n\nThe server exposes a single `browser_ai` tool that accepts natural language commands. It then:\n\n1. Uses Claude to interpret the command\n2. Generates a sequence of Playwright tool calls\n3. Executes them via the Playwright MCP client\n4. Returns a human-friendly summary\n\n## Troubleshooting\n\n### Authentication Issues\n\nIf you encounter authentication errors:\n\n1. Run `npx browser-ai --auth` to re-authenticate\n2. Ensure you have an active Claude Code subscription\n3. Check that the token hasn't expired\n\n### Connection Issues\n\nIf the server fails to connect to Playwright MCP:\n\n1. Ensure Playwright MCP is installed: `npm install -g @playwright/mcp`\n2. Check the `PLAYWRIGHT_MCP_PATH` environment variable\n3. Enable debug mode to see detailed logs\n\n### Tool Execution Errors\n\nIf commands fail to execute:\n\n1. Ensure the browser is in the expected state\n2. Try breaking complex commands into simpler steps\n3. Check the debug logs for specific error messages\n\n## Requirements\n\n- Node.js 18 or higher\n- Active Claude Code subscription\n- Playwright MCP server\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines before submitting PRs.\n\n## Support\n\nFor issues and feature requests, please use the GitHub issue tracker.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqckfx%2Fbrowser-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqckfx%2Fbrowser-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqckfx%2Fbrowser-ai/lists"}