capsolver-mcp
MCP Server for CapSolver — expose captcha-solving capabilities to AI agents via the Model Context Protocol.
Published on PyPI as capsolver-mcp and listed in the official MCP Registry as io.github.capsolver-ai/capsolver-mcp.
See the capsolver-ai-hub repo for integration examples and the full documentation.
For detailed MCP client setup (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and more), see docs/mcp-integration.md.
Install
pip install capsolver-mcp
pip install capsolver-mcp[browser]
All tools read the API key from the environment:
export CAPSOLVER_API_KEY="your-capsolver-api-key"
$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
set CAPSOLVER_API_KEY=your-capsolver-api-key
Usage
CLI
capsolver-mcp
capsolver-mcp --transport sse --host 0.0.0.0 --port 8000
capsolver-mcp --transport streamable-http --host 0.0.0.0 --port 8000
CLI options
capsolver-mcp [OPTIONS]
--transport {stdio,sse,streamable-http}
Transport protocol (default: stdio)
--host HOST Bind host for SSE/HTTP transports (default: 127.0.0.1)
--port PORT Bind port for SSE/HTTP transports (default: 8000)
--api-key KEY API key (fallback: CAPSOLVER_API_KEY env)
--name NAME Server name (default: capsolver)
Programmatic
from capsolver_mcp.server import create_server
server = create_server(
api_key="your-key",
server_name="capsolver",
host="127.0.0.1",
port=8000,
)
server.run(transport="sse")
Note: host and port are constructor parameters on create_server()
(forwarded to FastMCP), matching the MCP Python SDK 1.x API.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"capsolver": {
"command": "capsolver-mcp",
"env": {
"CAPSOLVER_API_KEY": "your-key"
}
}
}
}
To run without installing it globally, use "command": "uvx" with
"args": ["capsolver-mcp"] — this is what MCP clients generate from the
registry entry. See docs/mcp-integration.md for
per-client examples.
| Tool | Browser? | Description |
|---|
solve_captcha | No | Solve a captcha by type + site params (token mode) |
detect_captchas | Yes | Scan a page URL and list present captcha types |
solve_on_page | Yes | Detect + solve + autofill all captchas on a page |
get_balance | No | Check account balance and packages |
get_supported_captchas | No | List all supported captcha types and handlers |
Browser-based tools (detect_captchas, solve_on_page) require the browser extra:
pip install capsolver-mcp[browser]
playwright install chromium
Development
git clone https://github.com/capsolver-ai/capsolver-mcp.git
cd capsolver-mcp
uv sync --all-extras
uv run pytest
uv run ruff check src tests
License
MIT