CAPTCHA-MCP

验证码通用解决方案，chrome-mcp，可过点选、滑动验证码；旋转验证码需要自己扩展。

English | 中文

An MCP server that lets an AI assistant (Claude, etc.) see and operate a real Chrome window — open pages, take screenshots, and drive the real OS mouse to click and drag. Because the gestures are produced by the physical cursor rather than synthetic JavaScript events, the page receives trusted input, which is what makes it possible to solve interactive CAPTCHAs such as slider puzzles.

Why a "real mouse"?

Most browser-automation tools dispatch synthetic DOM events (element.click(), dispatchEvent(...)). Many anti-bot systems flag these because they carry isTrusted: false and have unnatural, instantaneous motion.

This project takes a different path: the MCP server moves the actual operating-system cursor with @nut-tree-fork/nut-js, using eased, human-like acceleration and wall-clock-paced timing. The cursor visibly moves on your screen, and the browser treats the input as genuine.

Related MCP server: Chrome MCP Server

Tools

Architecture

An MCP server cannot talk to Chrome directly, so the project ships with a small Chrome extension. The MCP server owns the OS mouse; the extension does the page-to-screen geometry (turning CSS-pixel targets into absolute screen coordinates).

MCP Client (Claude)
      │  stdio
      ▼
MCP server (Node)  ──── drives the real OS mouse (nut-js) ────►  your screen
      │  WebSocket :7891
      ▼
Chrome extension (MV3 service worker)
      │  chrome.tabs / chrome.scripting
      ▼
The web page

Multi-session bridge. Every MCP client spawns its own copy of the server, but they can't all bind the same WebSocket port. The first instance to bind :7891 becomes the bridge that owns the single extension connection; later instances detect the port is taken and run as clients, forwarding their calls through the bridge. This lets several concurrent Claude sessions share one Chrome connection.

Setup

1. Install the server

npm install

2. Load the Chrome extension

1. Open chrome://extensions

2. Toggle Developer mode (top-right)

3. Click Load unpacked and select the extension/ folder

The extension's service worker keeps a WebSocket open to ws://127.0.0.1:7891 and reconnects automatically (a chrome.alarms timer wakes it about every 24 s).

3. Register the MCP server with your client

Claude Code:

claude mcp add chrome -- node /absolute/path/to/CAPTCHA-MCP/server/index.js

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "chrome": {
      "command": "node",
      "args": ["/absolute/path/to/CAPTCHA-MCP/server/index.js"]
    }
  }
}

Restart the client. The server starts the WebSocket bridge automatically; the extension connects once both are running.

macOS permission: moving the real mouse requires Accessibility access. Grant your MCP client (Terminal / Claude / the host app) permission under System Settings → Privacy & Security → Accessibility.

Usage

Ask the assistant things like:

• "Open https://example.com" → open_url

• "Take a screenshot of the page" → screenshot (PNG returned + saved to ~/Downloads)

• "Screenshot just the .captcha element" → cropped element screenshot

• "Solve the slider: drag the handle #slider-btn right by 260px" → drag

• "Click the checkbox at this spot in the screenshot" → click with a selector + fraction

A typical slider-CAPTCHA flow: screenshot the puzzle → reason about the gap distance → drag the handle by that distance → screenshot again to confirm.

Configuration

Troubleshooting

• "No Chrome extension is connected" — Chrome isn't running, the extension isn't loaded/enabled, or the ports don't match. Check the service-worker console at chrome://extensions → service worker.

• The cursor doesn't move / drags do nothing — grant Accessibility permission (macOS, see above).

• Screenshot fails — make sure a normal web page is in the focused window; chrome:// pages and the extensions page can't be captured.

• Wrong drag/click position — coordinates assume the Chrome window is on the primary display and not zoomed by the OS; keep the target tab focused and fully visible.

• Port already in use — set CHROME_MCP_PORT and update WS_URL to match.

Project layout

server/index.js           MCP server + WebSocket bridge + OS-mouse driver
extension/manifest.json   MV3 manifest (tabs, alarms, scripting, <all_urls>)
extension/background.js   Service worker: connects + page→screen geometry

⚠️ Disclaimer

This tool drives a real browser with trusted input and can interact with anti-bot challenges. It is intended for authorized testing, research, accessibility, and automation of sites you own or have permission to use. You are responsible for complying with the terms of service and laws that apply to any site you point it at. Do not use it to abuse services or bypass protections without permission.

中文文档

English | 中文

一个 MCP 服务器，让 AI 助手（如 Claude）能够 看见并操作真实的 Chrome 窗口——打开网页、截图，并驱动真实的操作系统鼠标进行点击和拖拽。 由于这些动作来自物理光标，而非合成的 JavaScript 事件，网页收到的是 受信任的输入（trusted input），因此可以用来解决滑块验证码等交互式人机验证。

为什么要用"真实鼠标"？

大多数浏览器自动化工具发送的是合成 DOM 事件（element.click()、dispatchEvent(...)）。 很多反爬/风控系统会识别它们，因为这些事件带有 isTrusted: false，且运动轨迹瞬时、不自然。

本项目走了另一条路：MCP 服务器通过 @nut-tree-fork/nut-js 移动真正的操作系统光标， 采用缓动（ease-in-out）的拟人加速度，并按真实时钟精确控制时长。光标会在你的屏幕上真实移动， 浏览器把它当作真人输入。

工具

架构

MCP 服务器无法直接与 Chrome 通信，因此项目附带一个小型 Chrome 扩展。 MCP 服务器负责操控操作系统鼠标；扩展负责"页面→屏幕"的坐标换算 （把 CSS 像素目标转换成屏幕绝对坐标）。

MCP 客户端 (Claude)
      │  stdio
      ▼
MCP 服务器 (Node)  ──── 驱动真实操作系统鼠标 (nut-js) ────►  你的屏幕
      │  WebSocket :7891
      ▼
Chrome 扩展 (MV3 service worker)
      │  chrome.tabs / chrome.scripting
      ▼
网页

多会话桥接。 每个 MCP 客户端都会启动自己的服务器进程，但它们无法都绑定同一个 WebSocket 端口。第一个成功绑定 :7891 的实例成为桥（bridge），独占与扩展的连接；后续实例发现端口被占用后 作为**客户端（client）**运行，把调用转发给桥。这样多个并发的 Claude 会话就能共享同一个 Chrome 连接。

安装

1. 安装服务器依赖

npm install

2. 加载 Chrome 扩展

1. 打开 chrome://extensions

2. 打开右上角的开发者模式

3. 点击加载已解压的扩展程序，选择 extension/ 文件夹

扩展的 service worker 会保持一条到 ws://127.0.0.1:7891 的 WebSocket 连接， 并自动重连（chrome.alarms 定时器约每 24 秒唤醒一次）。

3. 在你的客户端中注册 MCP 服务器

Claude Code：

claude mcp add chrome -- node /CAPTCHA-MCP的绝对路径/server/index.js

Claude Desktop —— 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "chrome": {
      "command": "node",
      "args": ["/CAPTCHA-MCP的绝对路径/server/index.js"]
    }
  }
}

重启客户端。服务器会自动启动 WebSocket 桥；两端都运行后，扩展会自动连接。

macOS 权限： 移动真实鼠标需要"辅助功能"权限。请在 系统设置 → 隐私与安全性 → 辅助功能 中，为你的 MCP 客户端（终端 / Claude / 宿主应用）授予权限。

使用

你可以这样对助手说：

• "打开 https://example.com" → open_url

• "给当前页面截个图" → screenshot（返回 PNG，并保存到 ~/Downloads）

• "只截取 .captcha 这个元素" → 裁剪元素的 screenshot

• "解滑块：把把手 #slider-btn 向右拖 260 像素" → drag

• "点击截图中这个位置的复选框" → 带选择器 + 比例坐标的 click

典型的滑块验证码流程：screenshot 拍下拼图 → 推理缺口距离 → drag 把把手拖动相应距离 → 再次 screenshot 确认结果。

配置

故障排查

• "No Chrome extension is connected" —— Chrome 未运行、扩展未加载/未启用，或端口不匹配。 到 chrome://extensions → service worker 查看 service worker 控制台。

• 光标不动 / 拖拽无效 —— 授予辅助功能权限（macOS，见上文）。

• 截图失败 —— 确保聚焦窗口里是普通网页；chrome:// 页面和扩展页无法被截取。

• 拖拽/点击位置不对 —— 坐标假定 Chrome 窗口在主显示器上且系统未缩放；保持目标标签页聚焦且完整可见。

• 端口被占用 —— 设置 CHROME_MCP_PORT 并同步更新 WS_URL。

项目结构

server/index.js           MCP 服务器 + WebSocket 桥 + 操作系统鼠标驱动
extension/manifest.json   MV3 清单 (tabs, alarms, scripting, <all_urls>)
extension/background.js   Service worker：连接 + 页面→屏幕坐标换算

⚠️ 免责声明

本工具会以受信任的输入驱动真实浏览器，可与反爬/人机验证交互。它仅用于 经过授权的测试、研究、无障碍辅助，以及对你拥有或获得许可的网站进行自动化。 你需自行遵守所指向网站的服务条款及适用法律。请勿在未经许可的情况下用它滥用服务或绕过防护。