Local Jina Reader MCP

A small stdio MCP adapter for a self-hosted Jina Reader instance.

The Reader service does the browser work and Markdown extraction. This project only exposes one safe, local MCP tool so an Agent can call it when web content is needed.

Architecture

Agent --stdio MCP--> jina-reader-mcp --HTTP--> Jina Reader OSS

The adapter defaults to http://127.0.0.1:3000, uses one in-flight fetch, limits each URL to 8,000 Reader tokens, and rejects obvious local or private targets. It exposes read_url for one page and read_urls for a bounded batch of up to two pages.

Related MCP server: @hauntapi/mcp-server

Run the Reader backend

Docker is required for the upstream Reader image:

docker run --rm -p 127.0.0.1:3000:8081 ghcr.io/jina-ai/reader:oss

Smoke-test it:

curl.exe -X POST http://127.0.0.1:3000/ `
  -H "Accept: text/markdown" `
  -H "Content-Type: application/json" `
  -d '{"url":"https://example.com"}'

Run the MCP adapter

uv run --with . jina-reader-mcp

Or install it into a virtual environment:

uv sync
uv run jina-reader-mcp

The MCP server uses stdio, so configure your Agent to launch jina-reader-mcp from this checkout. The tools are named read_url and read_urls.

Example stdio configuration:

{
  "mcpServers": {
    "local-jina-reader": {
      "command": "uv",
      "args": ["run", "--directory", "D:/path/to/jina-reader-mcp-local", "jina-reader-mcp"],
      "env": {
        "READER_BASE_URL": "http://127.0.0.1:3000"
      }
    }
  }
}

Configuration

read_urls returns a JSON object with one result per input URL. A failed URL is reported as an error entry without discarding successful results from the same batch. The batch is capped at two URLs and still passes through the adapter's global concurrency limit.

Search is intentionally not exposed yet: the self-hosted Reader search process needs a populated local index or an external Google/Bing SERP provider, neither of which is available in the default stateless setup. The adapter also does not pretend that X-Max-Tokens is resumable pagination; add a continuation protocol only if a Reader response contract provides a real cursor.

Development

uv sync
uv run python -m unittest discover -s tests -v

License

MIT