pdf-mcp

Let your AI agent pull text and tables out of PDFs and Word documents. An MCP server for invoices, reports, statements, and lab documents, where the data lives in tables the model can't read from a pasted blob.

When you paste a document into a prompt, the columns collapse and the table turns to mush, so the model guesses at the numbers. This extracts the actual table structure with deterministic code, so the agent gets clean rows and never invents a cell.

What it turns a document into

A PDF or Word table like this:

Item     Qty   Price
Widget    3    12.50
Gadget    1    40.00
Bolt     10     0.25

comes back as structured rows (or CSV), not a flattened line of text:

[["Item","Qty","Price"],["Widget","3","12.50"],["Gadget","1","40.00"],["Bolt","10","0.25"]]

Related MCP server: pdfmux

The tools it gives an agent

Getting started (Claude Desktop)

The fastest way to use this is with an MCP client like Claude Desktop. Three steps:

1. Install it

pip install "pdf-agent-mcp[mcp]"

2. Add it to your client's config

Claude Desktop's config lives here:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server:

{
  "mcpServers": {
    "pdf": { "command": "pdf-agent-mcp" }
  }
}

3. Restart Claude Desktop. You'll see a tools icon appear, meaning the server is connected.

That's it. Now ask about any .pdf or .docx on your machine:

You:  Pull the line items out of /Users/me/invoices/2024-001.pdf

Agent (calls extract_tables):
  Item     Qty   Price
  Widget    3    12.50
  Gadget    1    40.00
  Bolt     10     0.25
  (the table extracted cleanly)

The agent reads the real table structure instead of a flattened blob, so nothing is misaligned.

Restricting file access: to stop the agent reading anything outside one folder, set PDF_MCP_ALLOWED_DIR. See SECURITY.md.

Use it with other MCP clients

The same server works in any MCP client, only the config differs. Use pdf-agent-mcp as the command.

Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Same shape as Claude Desktop, and it hot-reloads (no restart):

{ "mcpServers": { "pdf": { "command": "pdf-agent-mcp" } } }

VS Code / GitHub Copilot — .vscode/mcp.json. Note the different key (servers, not mcpServers) and the required type. Tools only run in Copilot Agent mode:

{ "servers": { "pdf": { "type": "stdio", "command": "pdf-agent-mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json (create it if missing). Same shape as Claude Desktop:

{ "mcpServers": { "pdf": { "command": "pdf-agent-mcp" } } }

Cline — add it from the extension's MCP settings panel in VS Code (command: pdf-agent-mcp).

Understanding the output

extract_tables returns the rows, plus an honest assessment of how reliable each table looks, so you can trust a clean table and double-check a shaky one:

{
  "page": 1,
  "rows": [ ... ],
  "n_rows": 4,
  "looks_clean": true,
  "column_count": 3,
  "empty_ratio": 0.0,
  "warnings": []
}

• looks_clean — true if the table extracted without red flags.

• column_count — the number of columns, if every row agrees on it (null if rows disagree).

• empty_ratio — fraction of blank cells. A high value often means a bad extraction.

• warnings — plain-language flags, e.g. "ragged: rows have [2, 3, 4] columns (grid may be misdetected)" or "66% of cells are empty". PDF tables are genuinely hard (nested/merged cells, multi-page), so instead of pretending, the tool tells you when a result is suspect.

Also usable from plain Python

from pdf_mcp import docx_extractor, extractor

extractor.extract_tables("invoice.pdf")      # {'tables': [{'rows': [...], 'looks_clean': True, ...}]}
extractor.table_to_csv("invoice.pdf")        # clean CSV of the first table
extractor.extract_text("report.pdf", page=1)

docx_extractor.extract_docx_tables("coa.docx")
docx_extractor.docx_table_to_csv("coa.docx")

Tests

python -m pip install -e ".[test]"
python -m unittest discover -s tests     # builds synthetic PDFs, runs anywhere

License

MIT