docreadi-mcp

A local MCP server for DocReadi — document data extraction for finance. It runs on your machine, reads documents off your disk, and calls the hosted DocReadi API with your API key, so an AI client (Claude Desktop, Claude Code, Cursor, …) can extract documents and query your DocReadi corpus without leaving the chat.

Status: v1 published — on PyPI as docreadi-mcp; run with uvx docreadi-mcp (see Install / configure below). Plan + history: ../../MCP_SERVER_PLAN.md.

How it works

Your MCP client spawns docreadi-mcp as a local subprocess and talks to it over stdio. The server is a thin courier — all extraction/storage happens on the hosted DocReadi API; the server just translates tool calls into HTTPS requests and (for ingestion) reads local files. Your API key lives only in your client config, never in this repo.

Install / configure

Add the server to your MCP client config with your DocReadi API key (get one at docreadi.com → Settings → API keys):

{
  "mcpServers": {
    "docreadi": {
      "command": "uvx",
      "args": ["docreadi-mcp"],
      "env": {
        "DOCREADI_API_KEY": "dr_live_…"
        // "DOCREADI_BASE_URL": "https://docreadi.com"  // override if self-hosting
      }
    }
  }
}

Tools

(search_documents is the raw query surface; for richer column selection and saved queries, author a report in the UI and use run_report / export_report_csv.)

Verify your key (--check)

Before wiring it into a client, confirm the service is reachable and your key works — straight from a terminal, no MCP client needed:

DOCREADI_API_KEY=dr_live_… uvx docreadi-mcp --check
# ✓ Connected — DocReadi reachable at https://docreadi.com, API key valid.

Exit code: 0 connected · 1 reachable but the key failed · 2 no key set. (docreadi-mcp --version prints the version; no flags runs the server over stdio.)

Development

This package lives in the DocReadi monorepo so it's reviewed and CI'd alongside the API it wraps. Its layering keeps the dependency-free parts testable in the main CI without the mcp SDK:

• docreadi_mcp/config.py — env config.
• docreadi_mcp/catalog.py — pure-data tool→endpoint registry (the maintenance anchor: tests/test_mcp_catalog_contract.py binds it to agent_guide.GUIDE).
• docreadi_mcp/client.py — httpx client (tested with MockTransport).
• docreadi_mcp/server.py — thin FastMCP glue (lazy-imports the mcp SDK).

# from the repo root
pip install -e services/mcp          # installs mcp + httpx
DOCREADI_API_KEY=dr_… python -m docreadi_mcp   # run over stdio

Maintenance contract: when a DocReadi API endpoint a tool wraps changes, update docreadi_mcp/catalog.py (and the tool) — the contract test fails CI otherwise. See MCP_SERVER_PLAN.md §5.