camofox-mcp

<!-- Badges --> <p align="left"> <!-- License --> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>

<!-- Tech stack --> <img src="https://img.shields.io/badge/TypeScript-5.0+-blue" />

<!-- MCP --> <img src="https://badge.mcpx.dev?type=server" title="MCP Server"/> </p>

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.

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

• Node.js >= 18
• A running camofox-browser server to connect to

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