{"id":50150714,"url":"https://github.com/brainfuel/mcp-browser","last_synced_at":"2026-05-24T08:03:25.381Z","repository":{"id":355021199,"uuid":"1222936976","full_name":"brainfuel/mcp-browser","owner":"brainfuel","description":"Native macOS browser exposed as an MCP server — agents drive a real WKWebView.","archived":false,"fork":false,"pushed_at":"2026-05-01T12:19:34.000Z","size":1425,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T14:17:17.258Z","etag":null,"topics":["ai-agents","browser-automation","claude","macos","mcp","mcp-server","model-context-protocol","swiftui","wkwebview"],"latest_commit_sha":null,"homepage":null,"language":"Swift","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/brainfuel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T21:17:55.000Z","updated_at":"2026-05-01T12:19:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/brainfuel/mcp-browser","commit_stats":null,"previous_names":["brainfuel/mcp-browser"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/brainfuel/mcp-browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainfuel%2Fmcp-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainfuel%2Fmcp-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainfuel%2Fmcp-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainfuel%2Fmcp-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brainfuel","download_url":"https://codeload.github.com/brainfuel/mcp-browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainfuel%2Fmcp-browser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33426013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"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-agents","browser-automation","claude","macos","mcp","mcp-server","model-context-protocol","swiftui","wkwebview"],"created_at":"2026-05-24T08:03:24.506Z","updated_at":"2026-05-24T08:03:25.376Z","avatar_url":"https://github.com/brainfuel.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Browser\n\nA native macOS web browser that exposes itself as a [Model Context Protocol](https://modelcontextprotocol.io) server, so AI agents can drive a real WKWebView the same way a person would — navigate, click, fill forms, read the DOM, take screenshots, run JavaScript, and capture network and console activity.\n\nBuilt with SwiftUI + WKWebView. The MCP server runs in-process over local HTTP with bearer-token authentication and DNS-rebinding defense.\n\n## Download\n\n**[⬇ Download the latest macOS build](https://github.com/brainfuel/mcp-browser/releases/latest)** — signed, notarised `.dmg` for Apple Silicon.\n\nAfter downloading, open the DMG and drag **MCP Browser** to your Applications folder.\n\n## Screenshots\n\n![MCP Browser window](docs/images/screenshot1.png)\n\n![MCP Browser tools and settings](docs/images/screenshot2.png)\n\n## Why\n\nMost \"browser-as-a-tool\" stories for agents fall into two camps:\n\n1. **Headless automation** (Playwright, Puppeteer) — fast and scriptable, but the agent never sees what *you* see, can't share your logged-in sessions, and runs in a different browser engine than the one you trust.\n2. **Remote-controlled cloud browsers** — your data leaves your machine, and you pay per session.\n\nMCP Browser is the third option: a real browser window on your Mac that you log into, navigate, and use yourself — and that an LLM can drive through MCP when you ask it to. Cookies, history, bookmarks, and downloads stay local. The agent sees the same page you do.\n\n## Features\n\n### Browser\n- **WKWebView**-backed tabs with a Safari-style tab strip (favicons, hover close, equal-width pills)\n- **URL bar** with history + bookmark autocomplete\n- **Bookmarks bar**, full bookmarks manager, history view, downloads popover\n- **Find on page**, zoom-per-host persistence, picture-in-picture controller\n- **Bookmark importer** (HTML / Safari / Chrome formats)\n- **Per-tab cookie and network capture**\n\n### MCP server\n- **Local HTTP transport** on port `8833` (configurable) — `POST /mcp` for JSON-RPC, `GET /mcp` for SSE-style status\n- **Bearer-token authentication** with a per-launch token, regeneratable from Settings\n- **DNS-rebinding defense** — `Host` header validated against `127.0.0.1` / `localhost`\n- **Auto-registration** with common MCP clients (Claude Desktop, Codex, etc.) via `MCPRegistrar`\n- **Tool action log** — every tool call is recorded with arguments, result summary, and timing\n\n### Tools (current catalog)\n- **Navigation** — `navigate`, `back`, `forward`, `reload`, `current_url`, `current_title`\n- **Tabs** — `list_tabs`, `new_tab`, `switch_tab`, `close_tab`\n- **DOM** — `click`, `fill`, `submit`, `hover`, `press_key`, `type_text`, `scroll`, `find_in_page`, `get_element`, `accessibility_tree`\n- **Page content** — `read_text`, `read_page`, `page_metadata`, `screenshot`, `pdf_export`, `render_html`, `eval_js`, `find`, `list_links`, `list_forms`\n- **Cookies / storage** — `get_cookies`, `set_cookie`, `storage`, `clear_session`\n- **Bookmarks** — `list_bookmarks`, `open_bookmark_folder`\n- **Inspection** — `console_logs`, `network_log`, `dialog`\n- **Files** — `download`, `upload_file` (gated by user permission)\n- **Misc** — `wait_for`, `emulate`, `resize`\n\nSee [`MCP Browser/MCP/MCPToolCatalog.swift`](MCP%20Browser/MCP/MCPToolCatalog.swift) for the authoritative list.\n\n### Privacy \u0026 safety\n- **Per-launch bearer token** — clients without it get `401 Unauthorized`\n- **Origin / Host validation** — blocks DNS-rebinding attacks from a malicious local web page\n- **User confirmation** for downloads, uploads, and any `dialog` interactions\n- **Local-only by default** — server binds to `127.0.0.1`, never the public network\n- **Action log** in Settings → you can see exactly what an agent has done in your browser\n\n## Requirements\n\n- macOS 14+ (Sonoma or later)\n- Xcode 16+ to build from source\n\n## Getting Started (users)\n\n1. Download the latest DMG from the [Releases](https://github.com/brainfuel/mcp-browser/releases/latest) page.\n2. Drag **MCP Browser** to `/Applications` and launch it.\n3. Open **Settings → Connection** to copy the bearer token and MCP endpoint URL.\n4. In your MCP client (Claude Desktop, Codex, etc.) add the server. The app's **Settings → MCP Clients** tab can patch the config for the most common clients automatically.\n5. Browse normally. When the LLM needs to do something on the web, it calls the tools through MCP and you'll see the action in the log.\n\n## Getting Started (developers)\n\n1. Clone this repository.\n2. Open [`MCP Browser.xcodeproj`](MCP%20Browser.xcodeproj) in Xcode.\n3. Select the `MCP Browser` scheme.\n4. Build and run on **My Mac**.\n\nCLI build:\n\n```bash\nxcodebuild -project \"MCP Browser.xcodeproj\" -scheme \"MCP Browser\" -configuration Debug build\n```\n\n### Building your own fork\n\nThe project ships with the original author's signing settings. If you're forking to build and ship your own copy:\n\n1. **Development team** — open the `MCP Browser` target in Xcode → **Signing \u0026 Capabilities** → pick your own team. This rewrites `DEVELOPMENT_TEAM` in `MCP Browser.xcodeproj/project.pbxproj`.\n2. **Bundle identifier** — change `PRODUCT_BUNDLE_IDENTIFIER` from `com.moosia.mcp-browser` to something you own.\n3. **No API keys are bundled.** MCP Browser doesn't call any LLM provider itself — it only serves tools to whatever client connects.\n\n## Configuring an MCP client\n\nMost MCP clients accept an HTTP transport block. Example for `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-browser\": {\n      \"transport\": \"http\",\n      \"url\": \"http://127.0.0.1:8833/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer \u003ctoken-from-settings\u003e\"\n      }\n    }\n  }\n}\n```\n\nThe bundled **MCP Clients** settings tab can write this for you for the clients it knows about (Claude Desktop, Codex, etc.) — pick the client, hit **Add MCP Browser**, and it'll patch the file in place.\n\nThe token rotates each time you click **Regenerate token** in Settings → Connection. Re-patch your clients after rotating.\n\n## Data Storage\n\n- Bookmarks, history, zoom-per-host, downloads, and the action log are stored locally with `PersistentStore` (file-backed) and SwiftData where appropriate.\n- The bearer token is stored in `UserDefaults`. It's regenerated from **Settings → Connection** whenever you want to revoke existing clients.\n- Favicons are cached on disk under Application Support.\n- No telemetry. No cloud sync. Nothing leaves the machine unless an MCP tool you invoke causes it to.\n\n## Project Structure\n\n```\nMCP Browser/\n├── Browser/         WKWebView wrapper, tab model, presenter, scripts, PiP\n├── MCP/             MCP server, JSON-RPC, host protocol, tool catalog\n│   ├── Registrar/   Auto-config patcher for Claude Desktop / Codex / etc.\n│   └── Tools/       Tool implementations (navigation, DOM, content, etc.)\n├── Settings/        Settings tabs (general, privacy, connection, recorder, etc.)\n├── Storage/         Bookmarks, history, downloads, favicons, action log\n├── Views/           Bookmarks bar, bookmarks manager, history, downloads popover\n├── ContentView.swift     Top-level window layout, tab strip, URL bar\n├── AppCommands.swift     Menu bar commands and keyboard shortcuts\n└── MCP_BrowserApp.swift  App entry point and environment wiring\n```\n\n**Key files**\n- [`MCP/MCPServer.swift`](MCP%20Browser/MCP/MCPServer.swift) — `NWListener`-based HTTP/JSON-RPC server, auth, rebind defense\n- [`MCP/MCPCoordinator.swift`](MCP%20Browser/MCP/MCPCoordinator.swift) — routes tool calls to the focused window's active tab\n- [`MCP/MCPToolCatalog.swift`](MCP%20Browser/MCP/MCPToolCatalog.swift) — registry of every exposed tool\n- [`MCP/MCPSecret.swift`](MCP%20Browser/MCP/MCPSecret.swift) — Keychain-backed bearer token\n- [`Browser/BrowserTab.swift`](MCP%20Browser/Browser/BrowserTab.swift) — per-tab `@Observable` model wrapping `WKWebView`\n- [`Browser/WebViewHost.swift`](MCP%20Browser/Browser/WebViewHost.swift) — `NSViewRepresentable` bridge\n\n## Security model\n\nMCP Browser deliberately runs **un-sandboxed** so it can:\n\n- Patch MCP-client config files in `~/Library/Application Support` / `~/.config`\n- Drive other apps (e.g. open external schemes) when explicitly asked\n\nIt does **not**:\n\n- Bind any network interface other than loopback (`127.0.0.1`)\n- Accept connections without the per-launch bearer token\n- Honor requests whose `Host` header doesn't match `127.0.0.1` or `localhost` (DNS-rebinding defense)\n- Send anything off the machine on its own\n\nIf you're audit-minded, the entire HTTP surface is in `MCP Browser/MCP/MCPServer.swift` and is roughly 400 lines.\n\n## Known Limitations\n\n- The action log isn't yet retroactively searchable from the UI.\n- Multi-window support exists but the MCP coordinator only routes to the most-recently-focused window.\n- The OAuth and basic-auth flows for sites are handled by WebKit; MCP Browser itself does not store passwords. Use the system keychain through Safari/Chrome import for now.\n- No mobile/iOS build — this is a Mac-only tool.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for how to file bugs, request features, and submit pull requests.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainfuel%2Fmcp-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrainfuel%2Fmcp-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainfuel%2Fmcp-browser/lists"}