JinDaGe - camoufox-mcp-python MCP Details

article

README

🚀 Camoufox MCP 服务器

Camoufox MCP 服务器是一个用 Python 编写的 MCP（模型上下文协议）服务器，借助 Camoufox 的反检测功能，提供完整的浏览器自动化操作。

🚀 快速开始

启动服务器

# 使用 uvx（推荐）
uvx camoufox-mcp

# 使用 uv（从源码启动）
uv run camoufox-mcp

# 或者作为模块启动
python -m camoufox_mcp

添加到 Claude Code

claude mcp add camoufox-mcp -- uvx camoufox-mcp

Claude 桌面端配置

将以下内容添加到你的 Claude 桌面端配置文件中：

{
  "mcpServers": {
    "camoufox-mcp": {
      "command": "uvx",
      "args": ["camoufox-mcp"]
    }
  }
}

或者如果你是从源码运行：

{
  "mcpServers": {
    "camoufox-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/camoufox-mcp-python",
        "camoufox-mcp"
      ]
    }
  }
}

✨ 主要特性

21 种浏览器自动化工具：可完全控制浏览器。
反检测功能：自动随机化指纹，避免被检测为机器人。
懒初始化：仅在首次调用工具时启动浏览器。
持久会话：浏览器在工具调用之间保持运行。
标签管理：支持多个标签页。
表单自动化：填充表单、上传文件、处理对话框。

📦 安装指南

快速开始（uvx - 推荐）

uvx camoufox-mcp

使用 pipx

pipx run camoufox-mcp

使用 pip

pip install camoufox-mcp
camoufox-mcp

从源码安装

# 克隆仓库
git clone https://github.com/rlgrpe/camoufox-mcp-python.git
cd camoufox-mcp-python

# 使用 uv 安装
uv sync

安装 Camoufox 浏览器

安装包后，你需要下载 Camoufox 浏览器二进制文件。命令取决于你安装包的方式：

如果通过 uvx 安装（推荐）

uvx camoufox fetch

如果通过 pipx 安装

pipx run camoufox fetch

如果通过 pip 安装

# macOS
python3 -m camoufox fetch

# Linux
python -m camoufox fetch

# Windows
camoufox fetch

如果从源码安装（uv）

uv run python -m camoufox fetch

Linux 系统依赖

在 Linux 上，你还需要安装系统依赖：

# Ubuntu/Debian
sudo apt install -y libgtk-3-0 libx11-xcb1 libasound2

# Arch
sudo pacman -S gtk3 libx11 libxcb cairo libasound alsa-lib

卸载浏览器二进制文件

# 使用与安装相同的方法：
uvx camoufox remove          # 如果使用 uvx
pipx run camoufox remove     # 如果使用 pipx
camoufox remove              # 如果使用 pip
uv run python -m camoufox remove  # 如果从源码使用 uv

💻 使用示例

基础用法

你可以按照上述快速开始部分的命令启动服务器，并根据需求调用不同的工具。例如，使用 browser_navigate 工具导航到指定 URL：

# 假设已经启动服务器，调用 browser_navigate 工具
# 这里需要根据实际的 MCP 调用方式来编写，示例代码仅为示意
# 实际调用可能会涉及到 MCP 协议的具体实现

📚 详细文档

工具参考

导航（4 个工具）

| 工具 | 描述 | |------|-------------| | browser_navigate | 导航到指定 URL | | browser_navigate_back | 返回上一页 | | browser_snapshot | 捕获当前页面的无障碍快照 | | browser_wait_for | 等待文本出现/消失或指定时间 |

交互（6 个工具）

| 工具 | 描述 | |------|-------------| | browser_click | 点击元素 | | browser_type | 在元素中输入文本 | | browser_hover | 悬停在元素上 | | browser_drag | 在两个元素之间进行拖放操作 | | browser_press_key | 按下键盘上的某个键 | | browser_select_option | 在下拉菜单中选择一个选项 |

页面（4 个工具）

| 工具 | 描述 | |------|-------------| | browser_evaluate | 在页面或元素上执行 JavaScript 代码 | | browser_console_messages | 获取控制台消息 | | browser_network_requests | 获取网络请求 | | browser_take_screenshot | 截取屏幕截图 |

表单（3 个工具）

| 工具 | 描述 | |------|-------------| | browser_fill_form | 填充多个表单字段 | | browser_file_upload | 上传文件 | | browser_handle_dialog | 处理对话框（警告、确认、提示） |

会话（4 个工具）

| 工具 | 描述 | |------|-------------| | browser_tabs | 列出、创建、关闭或选择标签页 | | browser_resize | 调整浏览器窗口大小 | | browser_close | 关闭浏览器 | | browser_install | 安装 Camoufox 浏览器 |

配置

可以通过 camoufox_mcp/config.py 中的 BrowserConfig 类来配置浏览器。可用选项如下： | 参数 | 类型 | 默认值 | 描述 | |-----------|------|---------|-------------| | os | str | None | 要模拟的操作系统（windows/macos/linux） | | headless | bool/str | False | 无头模式（或 'virtual'） | | humanize | bool/float | True | 模拟人类的光标移动 | | geoip | bool | True | 从 IP 自动检测地理位置 | | proxy | str/dict | None | 代理配置 | | block_webrtc | bool | True | 阻止 WebRTC 泄漏 | | block_webgl | bool | False | 阻止 WebGL 指纹识别 | | block_images | bool | False | 阻止图像加载 | | locale | str | None | 浏览器语言环境 | | viewport | dict | None | 视口尺寸 | | enable_cache | bool | True | 启用缓存 | | timeout | int | 30000 | 页面加载超时时间（毫秒） | | wait_strategy | str | "domcontentloaded" | 等待策略 | | ublock | bool | False | 启用 uBlock Origin |

代理配置示例

proxy = {
    'server': 'http://proxy.example.com:8080',
    'username': 'user',
    'password': 'pass'
}

🔧 技术细节

开发

# 安装开发依赖
uv sync --dev

# 运行测试
uv run pytest

# 格式化代码
uv run ruff format

# 代码检查
uv run ruff check

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

camoufox-mcp-python