{"id":51179230,"url":"https://github.com/tsaarni/mcpuppet","last_synced_at":"2026-06-27T06:04:47.957Z","repository":{"id":357211123,"uuid":"1235909069","full_name":"tsaarni/mcpuppet","owner":"tsaarni","description":"An MCP server that gives AI agents a local browser. ","archived":false,"fork":false,"pushed_at":"2026-06-26T06:00:08.000Z","size":327,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T08:02:53.733Z","etag":null,"topics":["ai-agents","ai-generated-code","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsaarni.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-05-11T19:16:34.000Z","updated_at":"2026-06-26T06:00:21.000Z","dependencies_parsed_at":"2026-06-26T08:01:06.515Z","dependency_job_id":null,"html_url":"https://github.com/tsaarni/mcpuppet","commit_stats":null,"previous_names":["tsaarni/mcpuppet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tsaarni/mcpuppet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fmcpuppet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fmcpuppet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fmcpuppet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fmcpuppet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsaarni","download_url":"https://codeload.github.com/tsaarni/mcpuppet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fmcpuppet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34843149,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"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","ai-generated-code","mcp-server"],"created_at":"2026-06-27T06:04:42.769Z","updated_at":"2026-06-27T06:04:47.949Z","avatar_url":"https://github.com/tsaarni.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# McPuppet\n\nAn MCP server that gives AI agents a local browser. It launches a Chrome/Chromium instance via Puppeteer and exposes tools to agents so they can navigate web pages and run searches.\nThe browser runs in non-headless mode by default so you can see what the agents are doing.\n\nEach MCP session gets a dedicated browser tab. The tab is created on first use and closed automatically when the session ends. Multiple agents can connect simultaneously, each with their own tab.\n\nContent is cleaned before being returned: hidden elements and HTML comments are stripped, boilerplate is removed, Mozilla Readability extracts the main article, and the result is converted to Markdown for more effective token usage. The output is wrapped in a tagged fence so agents know it's untrusted external content.\n\n## Tools\n\n- `fetch_url`: Navigate to a URL and return the full extracted Markdown content.\n- `search`: Run a web search and return the results page as Markdown. Accepts an optional `page` parameter (1-indexed) for navigating through result pages.\n\n## Quick start\n\n```bash\npnpm install  # to install dependencies\npnpm start\n```\n\nThe server starts on `http://127.0.0.1:5420` by default.\n\nTo build self-contained scripts (no `node_modules` needed at runtime):\n\n```bash\npnpm run build\n```\n\nThe output scripts `dist/mcpuppet-server` and `dist/mcpuppet-cli` can be run directly or copied to any directory on your PATH.\n\n## Configuration\n\nAll settings are controlled by environment variables:\n\n| Variable | Default | Description |\n|---|---|---|\n| `MCPUPPET_HOST` | `127.0.0.1` | Bind address |\n| `MCPUPPET_PORT` | `5420` | HTTP port |\n| `MCPUPPET_HEADLESS` | `false` | Run browser headless |\n| `MCPUPPET_SLOW_MO` | `0` | ms delay per Puppeteer action (for human observation) |\n| `MCPUPPET_MAX_CONNECTIONS` | `10` | Max concurrent sessions |\n| `MCPUPPET_REQUEST_TIMEOUT_MS` | `30000` | Page request timeout (msec) |\n| `MCPUPPET_SETTLE_DELAY_MS` | `1000` | Maximum wait after page load for network to settle before extracting content (msec) |\n| `MCPUPPET_MAX_REDIRECTS` | `5` | Maximum number of HTTP redirects to follow |\n| `MCPUPPET_SEARCH_BACKEND` | `duckduckgo` | Search provider (`google`, `duckduckgo`) |\n| `MCPUPPET_LOG_LEVEL` | `info` | Log verbosity (`debug`, `info`, `warn`, `error`) |\n| `MCPUPPET_EXECUTABLE_PATH` | _(empty)_ | Path to Chrome/Chromium executable (uses Puppeteer's bundled version if empty) |\n| `MCPUPPET_USER_DATA_DIR` | `./.browser-data` | Chrome/Chromium profile (persists cookies across restarts) |\n| `MCPUPPET_SESSION_DEBUG_DIR` | _(empty)_ | Directory for session debug dumps (disabled when empty) |\n| `MCPUPPET_AUTH_TOKEN` | _(empty)_ | Bearer token required on all requests (unauthenticated if unset) |\n\nYou can use environment variables directly or load them from an environment file.\nRefer to [`.env.example`](.env.example) as a template.\n\nTo use custom env file run\n\n```\nnode --strip-types --env-file=mysettings.env src/main.ts\n```\n\n\u003e [!WARNING]\n\u003e When `MCPUPPET_AUTH_TOKEN` is not set the server accepts all requests without authentication. It is intended for localhost use only (`MCPUPPET_HOST=127.0.0.1`). Do not expose it on a network interface without setting a token.\n\n\u003e [!NOTE]\n\u003e **Ubuntu 23.10+:** Puppeteer's bundled Chromium fails with `No usable sandbox!` due to [AppArmor user namespace restrictions](https://github.com/puppeteer/puppeteer/issues/12818). Mcpuppet automatically prefers `/opt/google/chrome/chrome` on Linux when available. You can also set `MCPUPPET_EXECUTABLE_PATH` to point to a Chrome/Chromium executable.\n\n## Adding to Kiro as a remote MCP server\n\nEdit `~/.kiro/agents/\u003cagent\u003e.json` (agent-specific) or `~/.kiro/settings/mcp.json` (user-wide) or `.kiro/settings/mcp.json` (workspace):\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpuppet\": {\n      \"url\": \"http://127.0.0.1:5420/mcp\"\n    }\n  }\n}\n```\n\n## Using via agent skills (without MCP)\n\nIn environments without MCP support, agents can use the CLI client `mcpuppet-cli` ([`src/cli.ts`](src/cli.ts)) to communicate with the server.\n\nInclude instructions like the following in a skill file to tell the agent how to use the CLI:\n\n```markdown\n---\nname: mcpuppet\ndescription: Fetch web pages and run web searches via a local browser. Use when you need to read documentation or search the internet.\n---\n\nUse following commands to interact with the browser:\n\n- `mcpuppet-cli fetch \u003curl\u003e` — Fetch a web page\n- `mcpuppet-cli search \u003cquery\u003e` — Run a web search\n```\n\n## Contributing\n\nPlease refer to [CONTRIBUTING.md](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsaarni%2Fmcpuppet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsaarni%2Fmcpuppet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsaarni%2Fmcpuppet/lists"}