web-search-mcp

An MCP server that exposes a real, cited web_search tool by shelling out to the Claude Code CLI running inside an isolated Docker container, logged into a personal claude.ai Pro subscription.

Why this exists

Some environments proxy Claude Code through a gateway (e.g. an internal LiteLLM-style proxy) that doesn't support Anthropic's built-in web_search server tool for the model it routes to. This project sidesteps that entirely: it's a separate, single-purpose MCP tool backed by its own Claude Code CLI session, running in a container so its login never touches the host's own Claude Code config.

See docs/superpowers/specs/2026-07-28-web-search-mcp-design.md for the full design rationale, including why a raw Anthropic API key doesn't work for this and why Docker isolation is necessary.

Related MCP server: Claude Web Search MCP Server

How it works

MCP client ──tool call──▶ server.py (FastMCP, stdio) ──subprocess──▶ docker run --rm -v claude-pro-home:/root web-search-claude:latest
                                                                            │
                                                                            ▼
                                                            Claude Code CLI, logged into a Pro account
                                                            (real web_search tool, real Anthropic models)

server.py runs docker run per query, parses the CLI's JSON output, and returns the answer text (which includes a Sources: section whenever the CLI actually searched).

Setup

Requires Docker and uv.

git clone https://github.com/bartdorlandt/web-search-mcp.git
cd web-search-mcp
uv sync

# Build the image (bundles the Claude Code CLI)
docker build -t web-search-claude:latest .

# Create a volume to hold the Pro-account login, then log in (interactive, opens a browser)
docker volume create claude-pro-home
docker run --rm -it -v claude-pro-home:/root web-search-claude:latest /login

The login only needs to happen once — the OAuth session persists in the claude-pro-home volume across container runs.

Manual test

uv run python -c "from server import _web_search_impl; print(_web_search_impl('What are today\'s top technology news headlines?'))"

Using it standalone

uv run python server.py

This starts the MCP server over stdio — point any MCP client at that command directly.

Adding it to gridctl

If you're using gridctl as an MCP gateway, add it as a local-process server in your stack.yaml:

mcp-servers:
  - name: web-search
    command: [uv, run, --directory, /path/to/web-search-mcp, python, server.py]
    transport: stdio

Clone this repo to /path/to/web-search-mcp (or wherever you like) and update the path above, then gridctl reload. No env: block is needed — the only credential this tool uses lives in the claude-pro-home Docker volume, not in gridctl's variable store.

Repo: https://github.com/bartdorlandt/web-search-mcp

Notes

• No automated test suite — the wrapper's logic is thin enough that its correctness is verified functionally (see the design doc's Testing section).

• Calls are assumed serial, not concurrent — see "Operational assumptions" in the design doc.

• Every query bills against the logged-in account's subscription usage.