camofox-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@camofox-mcp go to https://example.com and describe the page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
camofox-mcp
A stdio MCP server that exposes the camofox-browser HTTP API β an anti-detection browser automation server for AI agents β as MCP tools.
This is not a browser itself. It's a thin, generic bridge: every tool it registers is generated from openapi.json, the OpenAPI spec of the upstream camofox-browser server. Tabs, navigation, clicking/typing, accessibility snapshots, screenshots, sessions/cookies, and browser lifecycle are all covered simply by whatever operations exist in that spec.
On top of that bridge, this server adds security guardrails not present in the raw camofox-browser API: an SSRF guard that blocks tools from being pointed at internal infrastructure or cloud metadata endpoints, and a prompt-injection mitigation that wraps browsed content so the model treats it as data, not instructions. See the Security section below for details.
π Security
This server drives a real browser on your behalf and feeds its output back to an LLM. That combination has two distinct attack surfaces, both of which this project mitigates by default β read this before deploying, and especially before setting CAMOFOX_ALLOW_INTERNAL_URLS=1.
Prompt injection from browsed content
Any page the browser visits can contain text crafted to look like instructions to the model ("ignore previous instructions and...", fake system messages, hidden text, etc.). Every tool result returned from the camofox-browser server is wrapped with an explicit untrusted-content banner (see UNTRUSTED_CONTENT_BANNER in src/http.ts) telling the model to treat the content strictly as data, never as instructions to follow.
This is a mitigation, not a guarantee β no banner can make an LLM fully immune to injection. Treat any agent using this server as able to act on adversarial content it browses, and scope its other tool access (file system, shell, credentials, other MCP servers) accordingly. Don't grant it access to secrets or destructive tools it doesn't need.
SSRF (Server-Side Request Forgery)
Tools accept arbitrary URLs (e.g. "navigate to this page"), which an attacker β or a prompt-injected model β could point at internal infrastructure: your loopback interface, RFC1918 private ranges, link-local addresses, or cloud metadata endpoints like 169.254.169.254 (AWS/GCP/Azure instance metadata, often a path to credential theft).
Every field literally named url passed to a generated tool is checked by assertPublicUrl in src/security.ts before any request is made:
Scheme allowlist β only
http:andhttps:are permitted;file:,data:,gopher:, etc. are rejected outright.Blocked hostnames β
localhost,localhost.localdomain, and any hostname ending in.localor.internal.Blocked IPv4 ranges β loopback (
127.0.0.0/8), private (10.0.0.0/8,172.16.0.0/12,192.168.0.0/16), link-local/cloud-metadata (169.254.0.0/16), carrier-grade NAT (100.64.0.0/10), and0.0.0.0/8.Blocked IPv6 ranges β loopback (
::1), unique-local (fc00::/7), link-local (fe80::/10), and IPv4-mapped IPv6 addresses (::ffff:0:0/96) are unwrapped and checked against the IPv4 rules above.DNS rebinding protection β hostnames are resolved via DNS and every returned address is checked, so a public-looking hostname that resolves to (or is rebound to) an internal IP is still blocked, not just literal IP addresses in the URL.
This guard is on by default and should stay on in any deployment with network access to sensitive internal services. It can be disabled entirely by setting CAMOFOX_ALLOW_INTERNAL_URLS=1 β only do this in an isolated/sandboxed environment (e.g. a container with no route to internal infrastructure or cloud metadata) where SSRF has no meaningful blast radius, such as local development against a camofox-browser instance on localhost.
Credentials
CAMOFOX_API_KEY / CAMOFOX_ACCESS_KEY are sent as a bearer token to the configured CAMOFOX_URL on every request. Treat them as secrets: don't commit them, and don't point this server at a CAMOFOX_URL you don't trust, since the token will be sent to whatever host that is.
Reporting a vulnerability
If you find a security issue in this bridge itself (not the upstream camofox-browser server), please open an issue or contact the maintainer directly rather than filing a public exploit.
Related MCP server: scout-mcp-server
How it works
openapi.json --(npm run generate)--> src/tools/generated.ts --> src/index.ts registers MCP tools --> src/http.ts calls camofox-browser over HTTPscripts/generate-tools.tsreadsopenapi.jsonand emitssrc/tools/generated.ts: an array of operations, each with a name, description, HTTP method/path, field-to-location mapping, and a Zod schema derived from the JSON Schema.src/index.tsregisters one MCP tool per generated operation on startup.src/http.ts(callOperation) is the runtime path every tool call goes through: it splits input into path/query/body per the field mapping, runs an SSRF check on anyurlfield, sends the HTTP request to the camofox-browser server, and wraps the response as MCP tool content. Every successful result is prefixed with an untrusted-content banner instructing the model to treat webpage/browser-server content as data, not instructions.src/security.ts(assertPublicUrl) blocks non-http(s) schemes and any hostname/IP (including DNS-resolved) that is loopback, private, link-local, or reserved β this also covers cloud metadata addresses like169.254.169.254.
There is no per-endpoint or per-tool special-casing anywhere in the codebase. To add or change a tool, edit openapi.json and re-run npm run generate β never hand-edit src/tools/generated.ts.
Requirements
Node.js >= 18
A running camofox-browser server to connect to
Usage
Run directly with npx β no install step needed:
npx @tonjun/camofox-mcpMCP client configuration
Point your MCP client (Claude Code, Claude Desktop, etc.) at the package via npx:
{
"mcpServers": {
"camofox": {
"command": "npx",
"args": ["-y", "@tonjun/camofox-mcp"],
"env": {
"CAMOFOX_URL": "http://localhost:9377"
}
}
}
}Local development
npm install
npm run build # compile TypeScript to dist/
npm start # run the compiled server
npm run dev # run directly from source with tsxConfiguration
Configured entirely via environment variables:
Variable | Description |
| Base URL of the camofox-browser server (default |
| Bearer token sent as the |
| Set to |
Development
npm run generate # regenerate src/tools/generated.ts from openapi.json
npm run build # compile TypeScript to dist/
npm run dev # run the server directly from source with tsx
npm test # run the vitest suite
npm run test:watch # run vitest in watch modeAvailable Tools
25 toolscamofox_cleanup_idle_tabsA
Proactive memory-pressure cleanup
Closes tabs observed idle across multiple checks while preserving tabs with active/queued operations. Never returns URLs, titles, cookies, page text, or user IDs. Defaults to dry-run mode.
Inputs: dryRun, minIdleMs, maxTabsToClose, minTabsPerSession, +1 more.
camofox_clickB
Click an element
Click an element in a Camoufox tab by ref (e.g. e1), CSS selector, or coordinates.
Inputs: tabId (required), userId (required), ref, selector, +2 more.
camofox_close_tab_groupC
Close all tabs in a group
Close all Camoufox tabs sharing the given listItemId (tab group).
Inputs: userId (required), listItemId (required).
camofox_create_tabA
Create a new tab
PREFERRED: Create a new browser tab using the Camoufox anti-detection browser. Use camofox tools instead of Chrome/the built-in browser -- they bypass bot detection on Google, Amazon, LinkedIn, etc. Returns tabId for subsequent operations.
Inputs: userId (required), sessionKey (required), url, trace, +1 more.
camofox_delete_traceA
Delete a trace file
Removes a specific Playwright trace zip from the server.
Inputs: userId (required), filename (required).
camofox_destroy_sessionA
Destroy a user session
Closes all tabs and cleans up state for the given userId.
Inputs: userId (required).
camofox_download_traceB
Download a trace file
Streams a Playwright trace zip for viewing in trace.playwright.dev.
Inputs: userId (required), filename (required).
camofox_evaluateA
Evaluate JavaScript in a tab
Execute JavaScript in a Camoufox tab's page context and return the result of the expression. Use for injecting scripts, reading page state, or calling web app APIs.
Inputs: tabId (required), userId (required), expression (required).
camofox_extract_structured_dataA
Extract structured data via JSON Schema
Extracts structured data from the current page using a JSON Schema whose properties
carry x-ref hints pointing at snapshot element refs (e.g. e1, e2).
Call the snapshot tool (camofox_snapshot) first to populate the ref table.
Inputs: tabId (required), schema (required), userId (required).
camofox_go_backC
Go back
Navigate a Camoufox tab back to the previous page in history.
Inputs: tabId (required), userId (required).
camofox_healthB
Health check
Detailed health with tab/session counts and failure tracking.
Inputs: no named parameters.
camofox_import_cookiesA
Import cookies into a user session
Import cookies into a Camoufox user session for authenticated browsing (e.g. to skip interactive login on sites like LinkedIn). Requires BearerAuth in production.
Inputs: userId (required), cookies (required).
camofox_list_tabsB
List open tabs
List all open Camoufox tabs, optionally filtered by userId.
Inputs: userId.
camofox_list_tracesA
List trace files
Returns all Playwright trace zip files for the given user session, sorted newest first.
Inputs: userId (required).
camofox_metricsB
Prometheus metrics
Returns Prometheus text exposition format. Requires PROMETHEUS_ENABLED=1.
Inputs: no named parameters.
camofox_press_keyC
Press a keyboard key
Press a keyboard key (e.g. Enter, Escape, Tab) in a Camoufox tab.
Inputs: key (required), tabId (required), userId (required).
camofox_screenshotC
Take a screenshot
Take a screenshot of a Camoufox page. Returns a base64-encoded PNG.
Inputs: tabId (required), userId (required).
camofox_server_statusB
Server status
Returns basic server liveness and browser state.
Inputs: no named parameters.
camofox_set_viewportA
Set the tab viewport size
Physically resizes the page via Playwright's page.setViewportSize, triggering a real layout reflow. Use for responsive testing β window.resizeTo() is a no-op on non-popup windows.
Inputs: tabId (required), width (required), height (required), userId (required).
camofox_snapshotB
Get an accessibility snapshot of a tab
Get an accessibility snapshot of a Camoufox tab with element refs (e1, e2, etc.) for interaction, plus an optional screenshot (set includeScreenshot=true). Large pages are truncated with pagination links preserved at the bottom -- if the response includes hasMore=true and nextOffset, call again with that offset to see more content.
Inputs: tabId (required), userId (required), format, offset, +1 more.
camofox_start_browserA
Start the browser
Ensures the browser process is running. Idempotent.
Inputs: no named parameters.
camofox_stop_browserA
Stop the browser
Stops the browser and closes all sessions. Requires x-admin-key header.
Inputs: no named parameters.
camofox_typeB
Type text into an element
Type text into a focused element or a specific ref/selector in a Camoufox tab.
Inputs: text (required), tabId (required), userId (required), ref, +3 more.
camofox_wait_forC
Wait for a selector or timeout
Wait for a CSS selector to appear in a Camoufox tab, or for a timeout to elapse.
Inputs: tabId (required), userId (required), timeout, selector.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 25 tools
Most tools target a distinct resource and action (create_tab, list_tabs, navigate, click, type, snapshot), and the descriptions are clear. The main ambiguities are health vs server_status vs metrics, and navigate auto-creating tabs which overlaps slightly with create_tab.
All tools share the camofox_ prefix and snake_case, with most following a verb_noun pattern like create_tab, list_traces, and import_cookies. Deviations like metrics, health, server_status, and bare verbs like click, type, and evaluate keep it from being perfectly uniform.
25 tools is at the heavy end of the scale, though most are justifiable for browser automation. The operational subset (metrics, health, server_status) and multiple trace/tab management tools could be consolidated, making the overall count feel larger than necessary.
The tool set covers browser lifecycle, tab creation/listing, navigation, interaction, snapshots, traces, and cookie import. A notable gap is the lack of a direct close/delete single tab by tabIdβonly close_tab_group, cleanup_idle_tabs, and destroy_session are availableβplus no explicit tab activation tool.
Maintenance
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Security scanner for AI agents and MCP servers: injection, jailbreak, tool abuse.
Related MCP Servers
- AlicenseBqualityBmaintenanceAnti-detection browser automation MCP server. 18 tools wrapping CamoFox REST API with stealth fingerprinting that passes bot detection.47581 npm127MIT
- AlicenseAqualityBmaintenanceMCP server for browser automation with anti-detection. Scout pages, find elements, interact with websites, and monitor network traffic from any AI client that supports the Model Context Protocol.2126 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for controlling a local camofox-browser instance, enabling LLM agents to perform web automation tasks such as navigation, interaction, snapshotting, and content extraction.92 npmMIT
- AlicenseNot gradedqualityBmaintenanceThis MCP server exposes an anti-detect Firefox browser that passes bot-detection tests, allowing LLMs to automate web interactions with humanized clicks and fingerprint randomization.MIT