Skip to main content
Glama
camofox-mcp

camofox-mcp

by tonjun

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: and https: are permitted; file:, data:, gopher:, etc. are rejected outright.

  • Blocked hostnames β€” localhost, localhost.localdomain, and any hostname ending in .local or .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), and 0.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 HTTP
  • scripts/generate-tools.ts reads openapi.json and emits src/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.ts registers 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 any url field, 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 like 169.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

Usage

Run directly with npx β€” no install step needed:

npx @tonjun/camofox-mcp

MCP 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 tsx

Configuration

Configured entirely via environment variables:

Variable

Description

CAMOFOX_URL

Base URL of the camofox-browser server (default http://localhost:9377)

CAMOFOX_API_KEY / CAMOFOX_ACCESS_KEY

Bearer token sent as the Authorization header (accessKey takes precedence)

CAMOFOX_ALLOW_INTERNAL_URLS

Set to 1 to disable the SSRF guard in src/security.ts

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 mode

Available Tools

25 tools
camofox_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_navigateB

Navigate a tab to a URL or search macro

Navigate a Camoufox tab to a URL or use a search macro (@google_search, @youtube_search, etc.). Preferred over Chrome/the built-in browser for sites with bot detection. Auto-creates the tab if tabId is not found.

Inputs: tabId (required), userId (required), url, macro, +3 more.

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

    B3.1/5.0

    Scored across 25 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      21
      26 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      This 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