内容
# capsolver-mcp
适用于 [CapSolver](https://capsolver.com) 的 MCP 服务器 — 通过 [模型上下文协议](https://modelcontextprotocol.io) 向 AI 代理暴露验证码求解能力。
请参阅 [capsolver-ai](https://github.com/capsolver-ai/capsolver-ai) 仓库以获取集成示例和完整文档。
有关详细的 MCP 客户端设置（Claude Desktop、Claude Code、Cursor、Windsurf、Cline 等），请参阅 [docs/mcp-integration.md](docs/mcp-integration.md)。
## 安装
```bash
pip install capsolver-mcp
pip install capsolver-mcp[browser] # 带有 Playwright 支持（用于 detect/solve_on_page）
```
所有工具都从环境变量中读取 API 密钥：
```bash
# bash / zsh
export CAPSOLVER_API_KEY="your-capsolver-api-key"
# PowerShell
$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
# cmd
set CAPSOLVER_API_KEY=your-capsolver-api-key
```
## 使用
### 命令行界面
```bash
# 标准输入输出（默认 — 适用于本地 MCP 客户端，如 Claude Desktop）
capsolver-mcp
# SSE（用于远程 / HTTP 访问）
capsolver-mcp --transport sse --host 0.0.0.0 --port 8000
# 可流式 HTTP（MCP 2025-03-26 规范）
capsolver-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```
#### 命令行选项
```
capsolver-mcp [选项]
--transport {stdio,sse,streamable-http}
传输协议（默认：stdio）
--host HOST SSE/HTTP 传输的绑定主机（默认：127.0.0.1）
--port PORT SSE/HTTP 传输的绑定端口（默认：8000）
--api-key KEY API 密钥（备用：CAPSOLVER_API_KEY 环境变量）
--name NAME 服务器名称（默认：capsolver）
```
### 编程方式
```python
from capsolver_mcp.server import create_server
server = create_server(
api_key="your-key", # 或设置 CAPSOLVER_API_KEY 环境变量
server_name="capsolver", # 向 MCP 客户端广播的名称
host="127.0.0.1", # SSE / HTTP 传输的绑定主机
port=8000, # SSE / HTTP 传输的绑定端口
)
server.run(transport="sse") # 或 "stdio" 或 "streamable-http"
```
> **注意：** `host` 和 `port` 是 `create_server()` 的构造函数参数（转发到 `FastMCP`），匹配 MCP Python SDK (>=1.0) API。
## 在 Claude Desktop 中配置
添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"capsolver": {
"command": "capsolver-mcp",
"env": {
"CAPSOLVER_API_KEY": "your-key"
}
}
}
}
```
## 可用工具
| 工具 | 需要浏览器 | 描述 |
|---|---|---|
| `solve_captcha` | 否 | 按类型 + 网站参数求解验证码（token 模式） |
| `detect_captchas` | 是 | 扫描页面 URL 并列出存在的验证码类型 |
| `solve_on_page` | 是 | 检测 + 求解 + 自动填充页面上的所有验证码 |
| `get_balance` | 否 | 检查账户余额和套餐 |
| `get_supported_captchas` | 否 | 列出所有支持的验证码类型和处理程序 |
基于浏览器的工具（`detect_captchas`、`solve_on_page`）需要额外的 `browser`：
```bash
pip install capsolver-mcp[browser]
playwright install chromium
```
## 开发
```bash
git clone https://github.com/capsolver-ai/mcp-capsolver.git
cd mcp-capsolver
uv sync --all-extras # 或：pip install -r requirements-dev.txt
uv run pytest # 运行测试
uv run ruff check src tests # 校验
```
## 许可证
ISC
