pdf-extractor-mcp 0.1.1

MCP server exposing the PDF Extractor API as tools.

PDF Extractor MCP Server

A Model Context Protocol server that exposes the PDF Extractor API as tools so that LLM agents (Claude Desktop, Claude Code, Cursor, etc.) can extract images, tables, text blocks, formulas, and other elements from PDF documents.

Tools

Tool	Description
extract_elements	Extract elements from a single PDF (path, URL, or base64).
extract_elements_batch	Extract elements from multiple PDFs (Business tier).
list_extractions	Paginate the authenticated user's past extraction jobs.
get_extraction	Fetch details and files for a specific extraction.
delete_extraction	Delete an extraction job.
download_file	Fetch (and optionally save) a presigned Files[].Url from an extraction.

Install

Requires Python 3.10+. Pick whichever fits your workflow:

# Zero local setup — recommended for end users
uvx pdf-extractor-mcp

# Or a persistent install
pipx install pdf-extractor-mcp

# Or from source (for development)
cd mcp_server
python -m pip install -e ".[dev]"

Configure

Generate an API token at https://www.pdf-xtract.com/tokens and export it before running the server:

export PDF_EXTRACTOR_API_KEY=pxt_...
# Optional: point at a self-hosted deployment
# export PDF_EXTRACTOR_API_URL=https://pdf.example.com

Run

pdf-extractor-mcp
# or
python -m pdf_extractor_mcp

The server speaks MCP over stdio.

Claude Desktop / Claude Code config

Add this to claude_desktop_config.json (or your IDE's MCP settings). With uvx the package is fetched and cached on first run, so users don't need a prior pip install:

{
  "mcpServers": {
    "pdf-extractor": {
      "command": "uvx",
      "args": ["pdf-extractor-mcp"],
      "env": {
        "PDF_EXTRACTOR_API_KEY": "pxt_..."
      }
    }
  }
}

If you installed via pipx, replace "command": "uvx", "args": [...] with "command": "pdf-extractor-mcp".

Element categories

Caption, Footnote, Expression, Entry, Footer, Header, Image, SectionTitle, Table, Text, Title. Defaults to ["Image"].

Example prompts

• "Extract all tables from ~/Downloads/report.pdf as PNG and summarize the first one."
• "Pull every figure caption from pages 5-12 of https://arxiv.org/pdf/2401.12345.pdf."
• "List my extractions from the last week."

Testing the server

Three ways to exercise the server without a full IDE round-trip:

1. MCP Inspector (interactive UI):

   npx @modelcontextprotocol/inspector pdf-extractor-mcp
   

   Lists every tool, lets you fill in arguments, and shows the live response.

2. stdio smoke test — confirms the binary starts and registers tools:

   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
     | pdf-extractor-mcp
   

3. Unit tests (no network, no API key required):

   cd mcp_server
   pip install -e ".[dev]"
   pytest -m "not integration"
   

   An opt-in integration test exercises the live API; set a real key and run:

   PDF_EXTRACTOR_API_KEY=pxt_... pytest -m integration
   

Releasing

The MCP server is published to PyPI as pdf-extractor-mcp from the .github/workflows/mcp-server-release.yml workflow. To cut a release:

1. Bump version in mcp_server/pyproject.toml.
2. Tag the commit: git tag mcp-v0.1.0 && git push origin mcp-v0.1.0.
3. The workflow builds the sdist + wheel and publishes via PyPI Trusted Publishing (OIDC — no API token stored).

One-time PyPI setup (Trusted Publishing)

Before the first release, register a pending publisher on PyPI so it will accept the OIDC token. Without this the publish step fails with invalid-publisher: valid token, but no corresponding publisher.

1. Go to https://pypi.org/manage/account/publishing/.

2. Under "Add a new pending publisher", enter these values exactly (they must match the token claims the workflow produces):

   Field	Value
   PyPI Project Name	pdf-extractor-mcp
   Owner	BorisBesky
   Repository name	pdf-extractor
   Workflow name	mcp-server-release.yml
   Environment name	pypi

3. Make sure a GitHub environment named pypi exists (repo Settings → Environments). The release job declares environment: pypi; the name is case-sensitive and must match the PyPI entry above.

4. Re-run the release (re-push the tag, or trigger the workflow manually via "Run workflow").

Once the first publish succeeds, PyPI converts the pending publisher into a normal trusted publisher automatically — no further setup for later mcp-v* tags.

Notes

• Pass store_file=true (the default) for large PDFs - the API returns presigned URLs instead of base64 blobs. Use download_file to fetch them.
• When store_file=false, the server truncates FileData in its response summary and adds FileDataLength; the raw base64 stays available by calling the API directly if needed.
• OCR (ocr_mode=element|page) requires Starter or Business tier.
• Batch extraction requires Business tier.