CapSolver MCP Server: CAPTCHA Tools for AI Agents
TL;DR
capsolver-mcpmakes CapSolver available as a standard tool server for MCP-compatible AI clients.- Connected clients can discover five tools for solving, page detection, on-page handling, balance checks, and supported CAPTCHA types.
- The MCP client remains responsible for the conversation, permissions, tool approval, and the rest of the agent workflow.
- The server supports
stdio,SSE, andstreamable-httptransports.
Give MCP clients a dedicated CAPTCHA tool
An AI agent can navigate a browser, complete a form, and call external services, yet still stop when a CAPTCHA appears in an authorized workflow. Handling that step separately for every client creates duplicated adapters and different behavior across the stack.
capsolver-mcp provides one MCP server for that job. A compatible client connects to the server, discovers its tools, and calls the appropriate tool when a supported challenge needs to be handled. CapSolver returns the result; the client continues to manage the conversation, browser session, permissions, and final task.
This is useful for teams that use more than one MCP client or want CAPTCHA handling to remain a small, replaceable part of a larger agent system.
Five tools behind one connection
The server exposes five tools:
| Tool | Purpose |
|---|---|
solve_captcha |
Solve a supported challenge from its type and site parameters. |
detect_captchas |
Inspect a page and report the CAPTCHA types that are present. |
solve_on_page |
Detect, solve, and apply the result on a page. |
get_balance |
Check the CapSolver account balance and packages. |
get_supported_captchas |
Return the CAPTCHA types and handlers available to the server. |
The first three tools handle the workflow itself. The final two help an agent or operator check availability before starting a task.
Install and connect the server
Install the core package first, followed by the MCP server:
pip install capsolver-core
pip install capsolver-mcp
The browser-based tools require the browser extra and Chromium:
pip install "capsolver-mcp[browser]"
playwright install chromium
For a local MCP client, add the server command and API key to the client's MCP configuration:
{
"mcpServers": {
"capsolver": {
"command": "capsolver-mcp",
"env": {
"CAPSOLVER_API_KEY": "YOUR_API_KEY"
}
}
}
}
After the client reloads, it can discover the five tools from the server. If the executable is installed inside a virtual environment that the client cannot find, point the command to that environment's Python executable and start the capsolver_mcp module instead.
How it fits into an agent run
A typical run keeps a clear boundary between the client and CapSolver:
- The agent reaches a page in an authorized browser workflow.
- The client identifies that a supported CAPTCHA step needs attention.
- The client calls a CapSolver MCP tool with structured arguments.
- The server handles the requested CAPTCHA task and returns a structured result.
- The existing agent resumes the original workflow.
The MCP server does not replace the browser agent or decide what the overall task should be. It supplies a focused capability through a standard interface.
Local and remote transport options
stdio is the default transport and suits local clients that start the MCP server as a child process. The service also supports SSE and streamable-http for deployments that need an HTTP connection.
That choice affects how the client reaches the server, not which tools are available. Teams can therefore keep the same tool contract while changing the deployment model.
Where to start
The CapSolver MCP integration page gives a short overview of the workflow. The MCP service documentation covers installation, configuration, transports, and client examples. The source is available in the capsolver-mcp GitHub repository.
Use CapSolver only in lawful, authorized workflows. Tool availability does not grant permission to access private, restricted, or sensitive data, and teams should keep user approval visible for sensitive operations.
FAQ
Q: Does capsolver-mcp replace an MCP client or an agent framework?
No. capsolver-mcp provides callable tools, while the client or framework continues to manage the model, permissions, browser session, and overall workflow.
Q: Which clients can connect to the server?
Any client that supports external MCP servers and tool calls can use the same server pattern. The official documentation includes setup guidance and examples for common MCP clients.
Q: Are the browser tools installed by default?
No. detect_captchas and solve_on_page require the browser extra and a Playwright Chromium installation.
Q: Which transport should I use?
Use stdio for a local client that launches the server directly. Use SSE or streamable-http when the client needs to connect over HTTP.
