{
  "markdown": "<!-- mcp-name: io.github.wesseltl/pdf-mcp -->\n\n# pdf-mcp\n\n![CI](https://github.com/wesseltl/pdf-mcp/actions/workflows/ci.yml/badge.svg)\n![Python](https://img.shields.io/badge/python-3.10%2B-blue)\n![MCP](https://img.shields.io/badge/MCP-server-6E56CF)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n**Turn tables in PDF and Word documents into Excel, CSV, or JSON.** Use the simple browser app with\nno agent setup, or connect the same deterministic extraction tools to an AI agent through\n[MCP](https://modelcontextprotocol.io).\n\nThe browser app is for direct table conversion. It previews the extracted rows, highlights basic\nstructure warnings, and keeps files on your computer. Advanced profile checking can additionally\nvalidate named fields, preserve source evidence, and return `accepted`, `needs_review`, or\n`rejected` for a recurring document workflow. Cell values come from document parsers, not generated\nmodel output.\n\nNeed a profile and measured baseline for real documents? See the\n[Document Reliability Pilot](https://github.com/wesseltl/pdf-mcp/blob/main/BUY.md).\nAgents can use the structured offer at\n[`offers/document-to-excel-pilot.json`](https://raw.githubusercontent.com/wesseltl/pdf-mcp/main/offers/document-to-excel-pilot.json).\n\nWebsite: [simple conversion, local tools, and the free hosted agent beta](https://wesseltl.github.io/pdf-mcp/).\n\n> **Current limitation:** PDF extraction supports born-digital documents. Scanned or image-only PDFs\n> require OCR, which is not included. An `accepted` decision means the configured checks passed; it\n> does not prove that the source document itself is correct.\n\n## Simple browser app\n\nThis is the easiest way to use pdf-mcp. It requires no Python, terminal, MCP client, or agent\nconfiguration after downloading the app.\n\n1. Open the [v0.4.0 release](https://github.com/wesseltl/pdf-mcp/releases/tag/v0.4.0).\n2. Download the `pdf-mcp-app` ZIP for 64-bit Windows, an Apple silicon Mac, or 64-bit Linux.\n3. Unzip it and open `pdf-mcp-app`.\n4. Your browser opens. Drop in a PDF or Word document, choose Excel, CSV, or JSON, and select\n   **Convert document**.\n\nUse **Stop app** in the browser when finished. The app listens only on your computer. Temporary\ndocument copies are deleted immediately after conversion, and prepared downloads expire after 30\nminutes or when the app stops. The community beta downloads are currently unsigned, so the operating\nsystem may ask you to confirm that you want to open them.\n\nIf Python is already installed, the same interface can be started with:\n\n```bash\npython -m pip install \"pdf-agent-mcp @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl\"\npdf-mcp-app\n```\n\nThe simple app performs raw table extraction. “No basic structure problems detected” is not an\naccuracy guarantee. Check important values before using them, or use a profile-checked pilot for a\nrecurring business workflow.\n\n## For agents: local or free hosted beta\n\nThe normal `pdf-agent-mcp` command remains local, MIT licensed, network-free, and telemetry-free.\nFor people who explicitly want a measured agent beta, `pdf-agent-cloud-mcp` uploads only the selected\ndocument for one authenticated operation.\n\nProfile checking and evaluation currently run in the local edition or as part of the paid pilot. The\nfree hosted beta currently exposes raw text, table, and CSV extraction only.\n\n| Edition | Document location | Measurement | Best for |\n|---|---|---|---|\n| Local `pdf-agent-mcp` | Stays on your machine | None | Confidential or unrestricted local use |\n| Hosted `pdf-agent-cloud-mcp` | Temporary authenticated upload | Bounded operational counters | Redacted/non-sensitive beta evaluation |\n\nThe free hosted beta includes 25 operations per calendar month. Temporary uploads are deleted when\neach request completes. Usage metrics exclude filenames, document contents, extracted text, and\ntable cells. Applications are open while endpoint deployment is completed. Apply without attaching\na document; invitations begin only after the endpoint is verified:\n\n[Apply for free agent beta access](mailto:wesseltl@gmail.com?subject=pdf-mcp%20Free%20Agent%20Beta)\n\nAfter acceptance, install and configure the separate bridge with the endpoint and key you receive:\n\n```bash\npython -m pip install \"pdf-agent-mcp[cloud] @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl\"\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-cloud\": {\n      \"command\": \"pdf-agent-cloud-mcp\",\n      \"env\": {\n        \"PDF_MCP_CLOUD_URL\": \"https://endpoint-provided-with-beta-access.example\",\n        \"PDF_MCP_CLOUD_API_KEY\": \"key-provided-once\"\n      }\n    }\n  }\n}\n```\n\nUse only redacted or non-sensitive files. See the [free beta terms](BETA_TERMS.md),\n[privacy notice](PRIVACY.md), and machine-readable\n[`beta/free-hosted-beta.json`](beta/free-hosted-beta.json).\n\n## What it turns a document into\n\nA PDF or Word table like this:\n\n```\nItem     Qty   Price\nWidget    3    12.50\nGadget    1    40.00\nBolt     10     0.25\n```\n\ncan be checked against `invoice-lines-v1` and returned as canonical records with an explicit decision:\n\n```json\n{\n  \"decision\": \"accepted\",\n  \"profile\": {\"id\": \"invoice-lines-v1\", \"version\": \"1.0.0\"},\n  \"records\": [\n    {\n      \"values\": {\"item\": \"Widget\", \"quantity\": \"3\", \"unit_price\": \"12.50\"},\n      \"evidence\": {\n        \"item\": {\"page\": 1, \"table_index\": 0, \"row\": 1, \"column\": 0, \"bbox\": [242.9, 136.0, 287.7, 154.0]}\n      }\n    }\n  ]\n}\n```\n\n## The tools it gives an agent\n\n| Tool | What it does |\n|---|---|\n| `list_extraction_profiles()` | Built-in profile IDs, versions, fields, and hashes |\n| `extract_with_profile(path, profile)` | Canonical records, cell evidence, validation issues, and a fail-closed decision |\n| `export_with_profile(input_path, profile, output_path)` | Profile-checked `.xlsx`, `.csv`, or `.json`; XLSX includes Review, Data, and Evidence sheets |\n| `page_count(path)` | How many pages the PDF has |\n| `extract_text(path, page)` | Text per page (one page, or the whole doc) |\n| `extract_tables(path, page, merge_multipage)` | Raw rows, source coordinates, and basic parser warnings |\n| `table_to_csv(path, page, index)` | One table as clean CSV text |\n| `extract_docx_text(path)` | Paragraph text from a `.docx` file |\n| `extract_docx_tables(path)` | Word tables as rows of cells, with the same assessment fields and merged-cell warnings |\n| `docx_table_to_csv(path, index)` | One Word table as clean CSV text |\n| `export_document_tables(input_path, output_path, merge_multipage)` | Export PDF/DOCX tables to `.xlsx`, `.csv`, or `.json` |\n\n## MCP setup for Claude Desktop\n\nThe fastest way to use this is with an MCP client like Claude Desktop. Three steps:\n\n**1. Install it**\n\n```bash\npython -m pip install \"pdf-agent-mcp[mcp] @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl\"\n```\n\n**2. Add it to your client's config**\n\nClaude Desktop's config lives here:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAdd the server:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf\": { \"command\": \"pdf-agent-mcp\" }\n  }\n}\n```\n\n**3. Restart Claude Desktop.** You'll see a tools icon appear, meaning the server is connected.\n\nThat's it. Now ask about any `.pdf` or `.docx` on your machine:\n\n```\nYou:  Check /Users/me/invoices/2024-001.pdf with invoice-lines-v1.\n\nAgent (calls extract_with_profile):\n  decision: accepted\n  records: 3\n  issues: 0\n```\n\nThe agent must route `needs_review` and `rejected` results to a person instead of treating them as\ntrusted business data.\n\n> **Restricting file access:** to stop the agent reading anything outside one folder, set\n> `PDF_MCP_ALLOWED_DIR`. See [SECURITY.md](SECURITY.md).\n\n## Use it with other MCP clients\n\nThe same server works in any MCP client, only the config differs. Use `pdf-agent-mcp` as the command.\n\n**Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project). Same shape as Claude\nDesktop, and it hot-reloads (no restart):\n\n```json\n{ \"mcpServers\": { \"pdf\": { \"command\": \"pdf-agent-mcp\" } } }\n```\n\n**VS Code / GitHub Copilot** — `.vscode/mcp.json`. Note the different key (`servers`, not `mcpServers`)\nand the required `type`. Tools only run in Copilot **Agent mode**:\n\n```json\n{ \"servers\": { \"pdf\": { \"type\": \"stdio\", \"command\": \"pdf-agent-mcp\" } } }\n```\n\n**Windsurf** — `~/.codeium/windsurf/mcp_config.json` (create it if missing). Same shape as Claude\nDesktop:\n\n```json\n{ \"mcpServers\": { \"pdf\": { \"command\": \"pdf-agent-mcp\" } } }\n```\n\n**Cline** — add it from the extension's MCP settings panel in VS Code (command: `pdf-agent-mcp`).\n\n## Profile-checked extraction\n\nThe package includes `lab-coa-v1` and `invoice-lines-v1` as reference profiles:\n\n```bash\nextract-document-with-profile examples/invoice.pdf invoice-lines-v1 result.xlsx\n```\n\nExit status is 0 for `accepted`, 2 for `needs_review`, and 3 for `rejected`. XLSX output contains\n`Review`, `Data`, and `Evidence` sheets. Formula-like document values are escaped in spreadsheet\nexports rather than executed.\n\nProfiles are ordinary, versioned JSON contracts. See the\n[profile format](https://github.com/wesseltl/pdf-mcp/blob/main/PROFILE_FORMAT.md) and\n[machine-readable schema](https://github.com/wesseltl/pdf-mcp/blob/main/profile.schema.json).\nResults follow the versioned\n[extraction result schema](https://github.com/wesseltl/pdf-mcp/blob/main/extraction-result.schema.json).\n\n## Measure a profile\n\nMeasure exact field and record accuracy against local, customer-approved expected rows:\n\n```bash\nevaluate-document-profile evaluations/sample-invoice.json\n```\n\nThe report contains document hashes and aggregate metrics, not document or expected cell values. The\nincluded sample is synthetic; build a representative private set before claiming accuracy for a real\ndocument family. See the\n[evaluation guide](https://github.com/wesseltl/pdf-mcp/blob/main/EVALUATION.md).\n\nFor a larger demonstration, the repository includes an\n[18-document fictional workflow simulation](https://github.com/wesseltl/pdf-mcp/tree/main/evaluations/simulated-customer).\nIt exercises accepted, review, and rejected outcomes across PDF and DOCX variants. It is regression\ncoverage authored by the product developer, not customer validation or evidence of demand.\n\n## Raw export\n\nFor a direct document-to-file workflow, use the CLI:\n\n```bash\nexport-document-tables report.pdf report.xlsx\nexport-document-tables coa.docx coa.xlsx\nexport-document-tables coa.docx coa.json\n```\n\nRaw Excel exports include a `Review` sheet with table locations and parser warnings. Use profile-based\nexport when a workflow needs canonical fields and an acceptance decision.\n\n## Understanding the output\n\n`extract_tables` returns raw rows and lightweight parser diagnostics:\n\n```json\n{\n  \"page\": 1,\n  \"rows\": [ ... ],\n  \"n_rows\": 4,\n  \"looks_clean\": true,\n  \"column_count\": 3,\n  \"empty_ratio\": 0.0,\n  \"warnings\": []\n}\n```\n\n- **`looks_clean`** — `true` only means these basic diagnostics found no red flag. It is not an\n  accuracy score or acceptance decision.\n- **`column_count`** — the number of columns, if every row agrees on it (`null` if rows disagree).\n- **`empty_ratio`** — fraction of blank cells. A high value often means a bad extraction.\n- **`has_merged_cells`** — Word-only flag for tables with merged cells. Word exposes those cells as\n  repeated values, so the table is flagged for review.\n- **`warnings`** — plain-language flags, e.g. *\"ragged: rows have [2, 3, 4] columns (grid may be\n  misdetected)\"* or *\"66% of cells are empty\"*. PDF tables are genuinely hard (nested/merged cells,\n  multi-page), so instead of pretending, the tool tells you when a result is suspect.\n\n## Also usable from plain Python\n\n```python\nfrom pdf_mcp import docx_extractor, exporter, extractor, verified\n\nresult = verified.extract_with_profile(\"invoice.pdf\", \"invoice-lines-v1\")\nif result[\"decision\"] == \"accepted\":\n    rows = [record[\"values\"] for record in result[\"records\"]]\n\nverified.export_with_profile(\"coa.pdf\", \"lab-coa-v1\", \"coa.xlsx\")\n\nextractor.extract_tables(\"invoice.pdf\")      # {'tables': [{'rows': [...], 'looks_clean': True, ...}]}\nextractor.table_to_csv(\"invoice.pdf\")        # clean CSV of the first table\nextractor.extract_text(\"report.pdf\", page=1)\n\ndocx_extractor.extract_docx_tables(\"coa.docx\")\ndocx_extractor.docx_table_to_csv(\"coa.docx\")\n\nexporter.export_document_tables(\"coa.docx\", \"coa.xlsx\")\n```\n\n## Tests\n\n```bash\npython -m pip install -e \".[test]\"\npython -m unittest discover -s tests     # builds synthetic PDFs, runs anywhere\nevaluate-document-profile evaluations/sample-invoice.json\nevaluate-document-profile evaluations/simulated-customer/development.json\nevaluate-document-profile evaluations/simulated-customer/holdout.json\n```\n\n## License\n\nMIT\n",
  "bytes": 12872,
  "sha": "d96e7f0804c70ea809bc4d7e357f8e4b13cc380a224b1f72aa5b48001589b4a1",
  "repo_slug": "wesseltl/pdf-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wesseltl_pdf_mcp_4ec3be2d/readme"
}