CapSolver MCP Server

capsolver-mcp

Servidor MCP para CapSolver — expone capacidades de resolución de captchas a agentes de IA mediante el Protocolo de Contexto de Modelo.

Publicado en PyPI como capsolver-mcp y listado en el Registro MCP oficial como io.github.capsolver-ai/capsolver-mcp.

Consulta el repositorio capsolver-ai-hub para ejemplos de integración y la documentación completa.

Para una configuración detallada del cliente MCP (Claude Desktop, Claude Code, Cursor, Windsurf, Cline y más), consulta docs/mcp-integration.md.

Instalación

pip install capsolver-mcp
pip install capsolver-mcp[browser]   # with Playwright support (for detect/solve_on_page)

Todas las herramientas leen la clave de API desde el entorno:

# 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

Uso

CLI

# stdio (default — for local MCP clients like Claude Desktop)
capsolver-mcp

# SSE (for remote / HTTP access)
capsolver-mcp --transport sse --host 0.0.0.0 --port 8000

# Streamable HTTP (MCP 2025-03-26 spec)
capsolver-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Opciones de CLI

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)

Programático

from capsolver_mcp.server import create_server

server = create_server(
    api_key="your-key",       # or set CAPSOLVER_API_KEY env var
    server_name="capsolver",  # name advertised to MCP clients
    host="127.0.0.1",         # bind host for SSE / HTTP transports
    port=8000,                # bind port for SSE / HTTP transports
)
server.run(transport="sse")   # or "stdio" or "streamable-http"

Nota: host y port son parámetros del constructor en create_server() (reenviados a FastMCP), que coinciden con la API del SDK de MCP Python 1.x.

Configurar en Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "capsolver": {
      "command": "capsolver-mcp",
      "env": {
        "CAPSOLVER_API_KEY": "your-key"
      }
    }
  }
}

Para ejecutarlo sin instalarlo globalmente, usa "command": "uvx" con "args": ["capsolver-mcp"] — esto es lo que los clientes MCP generan desde la entrada del registro. Consulta docs/mcp-integration.md para ejemplos por cliente.

Herramientas disponibles

Herramienta	¿Navegador?	Descripción
solve_captcha	No	Resuelve un captcha por tipo + parámetros del sitio (modo token)
detect_captchas	Sí	Escanea una URL de página y lista los tipos de captcha presentes
solve_on_page	Sí	Detecta + resuelve + autocompleta todos los captchas en una página
get_balance	No	Consulta el saldo de la cuenta y los paquetes
get_supported_captchas	No	Lista todos los tipos de captcha y manejadores compatibles

Las herramientas basadas en navegador (detect_captchas, solve_on_page) requieren el extra browser:

pip install capsolver-mcp[browser]
playwright install chromium

Desarrollo

git clone https://github.com/capsolver-ai/capsolver-mcp.git
cd capsolver-mcp
uv sync --all-extras          # or: pip install -r requirements-dev.txt
uv run pytest                 # run tests
uv run ruff check src tests   # lint

Licencia

MIT