Skip to main content
Glama
diyaluo

pdf-extract-mcp

by diyaluo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

pdf-extract-mcp

A Model Context Protocol (MCP) server that extracts tables and text from digital (text-layer) PDFs — bank statements, invoices, bills — into CSV / JSON / Excel, with automatic PII redaction.

Part of the invoice-extractor product. This package is the MCP distribution channel ("ecosystem parasite": one backend, many host workflows). Web demo lives in the parent project.

What it does

  • extract_pdf — upload a digital PDF (base64 or URL), get back structured table rows as CSV / JSON records / XLSX. Sensitive fields are masked by default: national ID, phone, bank card, unified social credit code, email, passport, Chinese personal names, organization names.

  • health — service status and free-tier limits.

Scanned / image-only PDFs are explicitly rejected (SCANNED_PDF_UNSUPPORTED) — the free tier covers digital PDFs only (OCR is a paid-tier candidate).

Related MCP server: doc-intel MCP server

Limits (free tier)

  • 100 pages / rolling 30 days / client (anonymous, keyed by client hash).

  • 50 MB per file.

  • Above quota the tool returns a structured QUOTA_EXCEEDED response with an in-band upgrade pointer. It never silently bills.

  • Set PDF_EXTRACT_API_KEY to a paid key to bypass the quota (billing gateway is a P1 item; current free tier has no paid keys issued).

Run (local stdio — Claude Desktop / Cursor / any MCP client)

pip install -e .
pdf-extract-mcp

Client config example:

{
  "mcpServers": {
    "pdf-extract": {
      "command": "pdf-extract-mcp",
      "env": {}
    }
  }
}

Run (remote streamable-http, for hosted MCP clients)

REMOTE_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=5060 \
  python -m pdf_extract_mcp.server
# POST JSON-RPC to http://127.0.0.1:5061/mcp

Tool schema

extract_pdf(
  pdf_base64: str | None,     # preferred: PDF bytes as base64
  pdf_url:    str | None,     # alternative: direct https .pdf URL
  output:     "csv"|"json"|"xlsx",   # default csv
  redact_pii: bool = true,
  api_key:    str | None,    # paid key, optional
) -> {
  ok, type: "tables"|"text", pages, tables, rows, columns,
  csv | rows_json | xlsx_base64,   # depends on output
  elapsed_ms
}

Telemetry

Every call is appended (best-effort, never blocks extraction) to ../state/mcp_usage.jsonl. The P0 validation metric is real non-self traffic: third-party agents discovering and calling the server, not our own tests. Clients are recorded as salted hashes, no PDF content is logged.

Stack

mcp >= 1.2 (works on both mcp 1.x FastMCP and mcp 2.x MCPServer), pdfplumber, pandas, openpyxl. Python 3.10+.

License

MIT

Available Tools

2 tools
extract_pdfA

Extract tables from a digital (text-layer) PDF bank statement / invoice / bill into CSV, JSON rows, or Excel bytes (base64). PII is redacted by default. Scanned/image PDFs are rejected (no OCR in free tier).

Args: pdf_base64: PDF content as base64 (preferred — no third-party fetch). pdf_url: Direct HTTPS URL to a .pdf (alternative to base64). output: "csv" | "json" | "xlsx". redact_pii: keep true unless you explicitly need raw PII (paid only). api_key: paid key to bypass free quota (optional).

ParametersJSON Schema
NameRequiredDescriptionDefault
outputNocsv
api_keyNo
pdf_urlNo
pdf_base64No
redact_piiNo

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: PII redaction on by default, OCR absence and scanned-PDF rejection, a free quota that api_key bypasses, and the note that base64 avoids a third-party fetch. It stops short of describing quota size/rate limits or failure modes for corrupt or oversized PDFs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A front-loaded one-sentence summary of what/when/limits, followed by a tight Args block that maps one line per parameter. No filler sentences and no repetition of schema mechanics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-param tool with no annotations and no output schema, the description covers selection, safety-relevant behavior (redaction, rejection rules), and output encodings including that xlsx arrives as base64. It does not sketch the shape of returned JSON rows or error responses, which is the one remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all five parameters and it does: it names the output enum values, explains the base64-vs-url tradeoff, gives the intent and default rationale for redact_pii, and clarifies api_key is an optional paid quota bypass. This is meaning well beyond the bare anyOf/string typings.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (extract tables from a digital text-layer PDF) and narrows the document domain to bank statements/invoices/bills. It also names the output formats and the hard boundary (scanned/image PDFs rejected, no OCR), which no sibling or schema field conveys. An agent can distinguish this from the 'health' sibling instantly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames pdf_base64 as preferred and pdf_url as the alternative, tells the agent to keep redact_pii true unless raw PII is genuinely required (paid only), and states when the tool is NOT usable (scanned/image PDFs). This is when-to-use, when-not, and alternative-selection guidance in a few lines.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

healthA

Service health + free-tier limits. No auth required.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does add one genuinely useful behavioral fact — no authentication is needed — and implies a read-only diagnostic that reports free-tier limits. It says nothing about rate limits, caching, latency, or what a degraded result looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short clauses, no filler, and the primary purpose (service health) is front-loaded ahead of the scope detail. Nothing could be cut without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-annotation tool with no output schema, the definition covers what is needed to decide to call it: it is a health probe with free-tier limit data and no auth. It does not describe the shape of the returned status, which is a minor gap given the absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema is empty, so there are no parameter semantics to document. A baseline of 4 is appropriate; this dimension is effectively non-applicable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete resource and scope: service health status plus free-tier limit information. It is immediately distinguishable from the only sibling, extract_pdf, which is unrelated. It stops short of a 5 only because it is telegraphic rather than a full verb+resource statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'No auth required' hints at the calling context and removes a prerequisite, but the description never says when to invoke this versus anything else, nor what state or errors it signals. Usage is implied by the name and the health-check convention rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedextract_pdf
    • First observedhealth
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools serve clearly distinct purposes: health is a service-status check, while extract_pdf performs the core PDF extraction. There is no overlap or ambiguity in selection.

Naming Consistency4/5

extract_pdf follows a clear verb_noun convention, while health is a noun but is a conventional health-check name. The minor deviation is acceptable and readable.

Tool Count3/5

With only two tools, one being an ancillary health check, the functional surface is very thin. It is borderline appropriate for a narrowly scoped extraction service but feels minimal.

Completeness4/5

The core extraction operation supports multiple output formats, PII redaction, and both base64 and URL inputs. Notable gaps like OCR are explicitly out of scope for the free tier, leaving only minor workarounds needed.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Xberg MCP Server

    jamon8888
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server that extracts clean text, tables, and structured data from documents, images, code, and audio files, supporting 97 formats with OCR, transcription, and code intelligence.
    MIT

  • doc-intel MCP server

    avinashbadgu
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to extract structured data from PDFs with confidence scores and provenance, and to search, review, and correct documents via MCP tools, resources, and prompts.
    -

  • pdf-mcp

    wesseltl
    A
    license
    Not graded
    quality
    A
    maintenance
    Extracts text and tables from PDFs for AI agents via MCP, enabling structured data retrieval from invoices, reports, and statements.
    93 PyPI
    1
    MIT

  • InvoiceOracle

    ToolOracle
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to parse and analyze PDF invoices, including text, field, and table extraction, OCR for scanned documents, ZUGFeRD support, compliance validation, and batch processing via MCP.
    -