camofox-browser-mcp

MCP server for controlling a local camofox-browser instance.

quick installation

paste this into your llm agent session:

Install and configure camofox-browser-mcp by following the instructions here:
https://raw.githubusercontent.com/Microck/camofox-browser-mcp/refs/heads/main/INSTALL.md

npm (recommended)

npm install -g camofox-browser-mcp

MCP server for controlling a local jo-inc/camofox-browser instance.

This server exposes the full practical camofox-browser workflow to LLM agents: tab lifecycle, navigation, interaction, snapshots, screenshots, links, stats, cookie import, session cleanup, YouTube transcript extraction, and high-level composite helpers (navigate_and_snapshot, scroll_and_snapshot, fill_form, type_and_submit, batch_click, web_search).

Prerequisites

1. Node.js 22+ (required for the npm package)
2. Optional: Bun (recommended for local development): https://bun.sh/docs/installation
3. A running camofox-browser server (default http://127.0.0.1:9377)
4. Optional, depending on tools used:
   • CAMOFOX_API_KEY for cookie import
   • CAMOFOX_ADMIN_KEY for browser stop endpoint

Installation

Local development checkout

git clone https://github.com/Microck/camofox-browser-mcp.git
cd camofox-browser-mcp
bun install
bun run typecheck
bun run build

npm package

npm install -g camofox-browser-mcp

# optional smoke-run (most users just configure their MCP client)
camofox-browser-mcp

Configuration

Set these environment variables in your MCP client config.

Example MCP config (local build)

{
  "mcpServers": {
    "camofox-browser-mcp": {
      "command": "bun",
      "args": ["/absolute/path/to/camofox-browser-mcp/dist/index.js"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CAMOFOX_BASE_URL": "http://127.0.0.1:9377",
        "CAMOFOX_DEFAULT_USER_ID": "default-user",
        "CAMOFOX_DEFAULT_SESSION_KEY": "default-session",
        "CAMOFOX_API_KEY": "",
        "CAMOFOX_ADMIN_KEY": ""
      }
    }
  }
}

Tool coverage

The MCP toolset maps to camofox-browser endpoints and includes compatibility aliases for common camofox-mcp prompts.

Server and session tools

Tab lifecycle tools

Navigation and interaction tools

Content extraction tools

Supported web_search engines

web_search maps engine values to backend macros:

• google, youtube, amazon, reddit, wikipedia, twitter, yelp
• spotify, netflix, linkedin, instagram, tiktok, twitch

Compatibility notes

• list_profiles, save_profile, load_profile, and delete_profile are not exposed yet because current jo-inc/camofox-browser APIs do not provide cookie export/profile endpoints.

Typical workflow

1. camofox_start_browser
2. camofox_create_tab (or camofox_list_tabs + reuse)
3. camofox_navigate_tab
4. camofox_get_snapshot
5. Interact with refs: camofox_click, camofox_type, camofox_press, camofox_scroll
6. Re-run camofox_get_snapshot after major page changes
7. Cleanup with camofox_close_tab or camofox_close_session

Macro support

camofox_navigate_tab passes macro and query through to camofox-browser. Upstream macros include:

• @google_search
• @youtube_search
• @amazon_search
• @reddit_search
• @reddit_subreddit
• @wikipedia_search
• @twitter_search
• @yelp_search
• @spotify_search
• @netflix_search
• @linkedin_search
• @instagram_search
• @tiktok_search
• @twitch_search

Troubleshooting

• camofox_health fails: check CAMOFOX_BASE_URL and confirm backend is running.
• camofox_import_cookies 403: set CAMOFOX_API_KEY in both backend and MCP env.
• camofox_stop_browser 403: set CAMOFOX_ADMIN_KEY in both backend and MCP env.
• Missing refs after navigation: call camofox_get_snapshot again.

License

MIT