shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

crucible

一个基于Ruby的MCP服务器，使用Ferrum和Headless Chrome进行浏览器自动化，提供29种工具支持导航、交互、内容提取等功能，并内置反检测的隐身模式。

article

README

🚀 Crucible

Crucible 是一个基于 Ruby 的 MCP（模型上下文协议）服务器，它借助 Ferrum 和无头 Chrome 浏览器实现自动化操作。该项目提供了 29 种工具，可供 AI 代理控制浏览器，并且内置了隐身模式，能够有效躲避机器人检测。

🚀 快速开始

运行服务器

# 使用默认配置运行（无头模式，1280x720 视口，30 秒超时）
crucible

# 以可见浏览器模式运行
crucible --no-headless

# 完整选项
crucible \
  --no-headless \
  --width 1920 \
  --height 1080 \
  --timeout 60 \
  --chrome /usr/bin/chromium \
  --error-level debug

CLI 选项

| 选项 | 描述 | 默认值 | | --------------------------- | ------------------------------------------- | ----------- | | -c, --config FILE | YAML 配置文件的路径 | 自动检测 | | --[no-]headless | 是否以无头模式运行浏览器 | true | | -w, --width WIDTH | 视口宽度（像素） | 1280 | | -h, --height HEIGHT | 视口高度（像素） | 720 | | --chrome PATH | Chrome/Chromium 可执行文件的路径 | 自动检测 | | -t, --timeout SECONDS | 默认超时时间（秒） | 30 | | --error-level LEVEL | 日志记录级别（debug/info/warn/error） | warn | | --screenshot-format FMT | 默认截图格式（png/jpeg/base64） | png | | --content-format FMT | 默认内容格式（html/text） | html | | --[no-]stealth | 启用/禁用隐身模式 | true | | --stealth-profile PROFILE | 隐身模式配置文件（minimal/moderate/maximum） | moderate | | --stealth-locale LOCALE | 隐身模式下的浏览器区域设置 | en-US,en |

Claude Code 集成

gem install crucible

将以下内容添加到你的 Claude Code MCP 设置文件（~/.claude/settings.json）中：

{
  "mcpServers": {
    "crucible": {
      "command": "crucible",
      "args": ["--config", "~/.config/crucible/config.yml"]
    }
  }
}

✨ 主要特性

  • 提供 29 种工具，方便 AI 代理控制浏览器。
  • 内置隐身模式，可有效躲避机器人检测。
  • 支持多会话管理，可同时处理多个独立的浏览器实例。

📦 安装指南

使用 gem 安装

gem install crucible

从源码安装

git clone https://github.com/joshfng/crucible.git
cd crucible
bundle install

💻 使用示例

基础导航

navigate(url: "https://example.com")
wait_for(selector: ".content")
get_content(format: "text")

表单提交

navigate(url: "https://example.com/login")
type(selector: "#email", text: "user@example.com")
type(selector: "#password", text: "secret123")
click(selector: "button[type=submit]")
wait_for(selector: ".dashboard")

截图与 PDF 生成

# 视口截图（返回 base64）
screenshot()

# 全页截图
screenshot(full_page: true)

# 元素截图
screenshot(selector: ".hero-image")

# 保存到文件
screenshot(path: "/tmp/page.png")
screenshot(format: "jpeg", quality: 90, path: "/tmp/page.jpg")

# PDF 生成
pdf()                                    # 返回 base64
pdf(path: "/tmp/page.pdf")               # 保存到文件
pdf(format: "Letter", landscape: true)   # 自定义格式

JavaScript 执行

# 获取页面尺寸
evaluate(expression: "[window.innerWidth, window.innerHeight]")

# 滚动到顶部
evaluate(expression: "window.scrollTo(0, 0)")

# 获取元素数量
evaluate(expression: "document.querySelectorAll('a').length")

文件下载

# 设置下载目录
set_download_path(path: "/tmp/downloads")

# 点击下载链接并等待
click(selector: "a.download-btn")
wait_for_download(timeout: 30)

# 列出跟踪的下载文件（跨导航持久化）
list_downloads()

# 清除跟踪并删除文件
clear_downloads(delete_files: true)

📚 详细文档

工具列表

导航工具

| 工具 | 描述 | | ---------- | ----------------------------- | | navigate | 将浏览器导航到指定 URL | | wait_for | 等待元素出现 | | back | 后退到历史记录中的上一页 | | forward | 前进到历史记录中的下一页 | | refresh | 刷新当前页面 |

交互工具

| 工具 | 描述 | | --------------- | ----------------------------------------------------- | | click | 点击元素（支持双击、右键点击） | | type | 在输入框中输入文本（可选清空/提交） | | fill_form | 一次性填充多个表单字段 | | select_option | 从下拉菜单中选择选项 | | scroll | 将页面或元素滚动到可见区域 | | hover | 悬停在元素上 |

提取工具

| 工具 | 描述 | | ------------- | -------------------------------------------------------------------------------- | | screenshot | 截图（视口、全页或元素）；保存到文件或返回 base64 | | get_content | 获取页面内容（HTML 或文本） | | pdf | 生成页面的 PDF；保存到文件或返回 base64 | | evaluate | 执行 JavaScript 并返回结果 | | get_url | 获取当前页面的 URL | | get_title | 获取当前页面的标题 |

Cookie 工具

| 工具 | 描述 | | --------------- | ---------------------------------- | | get_cookies | 获取所有 Cookie 或特定 Cookie | | set_cookies | 设置一个或多个 Cookie | | clear_cookies | 清除所有或特定 Cookie |

会话工具

| 工具 | 描述 | | --------------- | -------------------------------- | | list_sessions | 列出所有活动的浏览器会话 | | close_session | 关闭一个会话或所有会话 |

下载工具

| 工具 | 描述 | | ------------------- | ------------------------------------------------- | | set_download_path | 设置下载目录 | | wait_for_download | 等待下载完成 | | list_downloads | 列出所有跟踪的下载文件 | | clear_downloads | 清除跟踪的下载文件（可选删除文件） |

隐身工具

| 工具 | 描述 | | --------------------- | ----------------------------------------------------- | | enable_stealth | 为会话启用隐身模式 | | disable_stealth | 为会话禁用隐身模式 | | get_stealth_status | 获取会话的隐身模式状态 | | set_stealth_profile | 更改隐身模式配置文件（minimal/moderate/maximum） |

会话管理

所有工具都接受一个可选的 session 参数，用于管理多个独立的浏览器实例：

# 在不同的浏览器中运行
navigate(session: "login-flow", url: "https://example.com/login")
navigate(session: "signup-flow", url: "https://example.com/signup")

# 列出活动会话
list_sessions()
# => { "count": 2, "sessions": ["login-flow", "signup-flow"] }

# 关闭特定会话
close_session(session: "login-flow")

# 关闭所有会话
close_session(all: true)

会话在首次使用时自动创建，并在显式关闭之前一直存在。

隐身模式

隐身模式应用了各种规避技术，使无头 Chrome 浏览器在机器人检测系统中看起来像普通浏览器。默认情况下，它以“moderate”配置文件启用。

隐身模式配置文件

| 配置文件 | 描述 | | ---------- | ------------------------------------------------------- | | minimal | 基本规避（navigator.webdriver、窗口尺寸） | | moderate | 适用于大多数用例的常见规避（默认） | | maximum | 针对最严格的机器人检测的所有规避 |

应用的规避技术

隐身模块包含从 puppeteer-extra 移植的规避技术：

  • navigator.webdriver - 移除 webdriver 标志
  • chrome.app - 模拟 chrome.app 对象
  • chrome.csi - 模拟 chrome.csi 函数
  • chrome.loadTimes - 模拟 chrome.loadTimes
  • chrome.runtime - 为扩展程序模拟 chrome.runtime
  • navigator.vendor - 覆盖 navigator.vendor
  • navigator.languages - 匹配 Accept-Language 标头
  • navigator.plugins - 模拟插件和 mimeTypes
  • navigator.permissions - 修复 Notification.permission
  • navigator.hardwareConcurrency - 设置合理的核心数
  • webgl.vendor - 修复 WebGL 供应商/渲染器
  • media.codecs - 报告对专有编解码器的支持
  • iframe.contentWindow - 修复 iframe 检测
  • window.outerdimensions - 修复 outerWidth/outerHeight
  • 用户代理覆盖 - 去除“Headless”并修复平台

运行时控制

# 检查隐身状态
get_stealth_status(session: "default")

# 启用最大保护的隐身模式
enable_stealth(session: "default", profile: "maximum")

# 禁用隐身模式（已应用的规避技术仍然有效）
disable_stealth(session: "default")

# 更改配置文件
set_stealth_profile(session: "default", profile: "minimal")

配置文件

创建 ~/.config/crucible/config.yml 文件：

browser:
  headless: true
  window_size: [1280, 720]

stealth:
  enabled: true
  profile: moderate
  locale: "en-US,en"

server:
  log_level: info

项目结构

crucible/
├── exe/crucible                # CLI 可执行文件
├── crucible.gemspec            # Gem 规范文件
├── Gemfile                     # 依赖文件
├── Rakefile                    # 构建任务文件
├── lib/
│   ├── crucible.rb             # 主模块
│   └── crucible/
│       ├── version.rb          # 版本常量
│       ├── configuration.rb    # 支持 YAML 的配置文件
│       ├── session_manager.rb  # 多会话管理
│       ├── server.rb           # MCP 服务器设置
│       ├── stealth.rb          # 隐身模式模块
│       ├── stealth/
│       │   ├── utils.js        # 隐身实用工具
│       │   └── evasions/       # 单个规避脚本
│       └── tools/
│           ├── helpers.rb      # 共享实用工具
│           ├── navigation.rb   # 导航工具
│           ├── interaction.rb  # 交互工具
│           ├── extraction.rb   # 提取工具
│           ├── cookies.rb      # Cookie 工具
│           ├── sessions.rb     # 会话工具
│           ├── downloads.rb    # 下载工具
│           └── stealth.rb      # 隐身控制工具
└── spec/                       # RSpec 测试文件

开发

# 运行测试
bundle exec rspec

# 运行代码检查
bundle exec rubocop

# 交互式控制台
bundle exec rake console

# 在开发环境中运行服务器
bundle exec rake server

发布

bin/release 0.2.0

此脚本会更新版本号、提交更改、打标签、推送代码、创建 GitHub 发布、构建 gem 并推送到 RubyGems（你需要通过浏览器处理 MFA）。

要求

  • Ruby >= 3.2.0
  • Chrome 或 Chromium 浏览器
  • 依赖项：
    • ferrum ~> 0.17.1
    • mcp ~> 0.4.0

📄 许可证

本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端