MCP

MCP server for AI clients

The PDF Extractor Model Context Protocol server lets a compatible AI client call the PDF Extractor API as tools. It runs locally and communicates with the client over standard input/output; PDF processing still uses the hosted API.

Requirements

• Python 3.10 or later
• uvx or pipx
• A PDF Extractor API token from API Tokens
• An MCP-compatible client

Install and configure

The shortest setup uses uvx, which downloads and caches the package automatically:

uvx pdf-extractor-mcp

Add this server definition to the MCP settings used by the client:

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

Save the configuration and restart the client. The exact settings filename and location depend on the client.

For a persistent installation:

pipx install pdf-extractor-mcp

Then set the command to pdf-extractor-mcp and remove the args entry.

Available tools

Tool	Purpose
extract_elements	Extract elements from one PDF path, URL, or base64 value
extract_elements_batch	Extract several PDFs; Business plan required
list_extractions	List saved extraction jobs
get_extraction	Read one saved job and its files
delete_extraction	Delete a saved extraction
download_file	Download a result from a stored-file URL

Category values are Caption, Footnote, Expression, Entry, Footer, Header, Image, SectionTitle, Table, Text, and Title. Image is the default.

Example prompts

• “Extract images and captions from pages 5–12 of this PDF.”
• “Extract the tables from this report and save the result files.”
• “List my extractions from the last seven days.”

The AI client decides how to translate a prompt into tool arguments. Review requests involving deletion or sensitive files before approving them.

OCR and table options

• Set ocr_mode to element or page when text recognition is needed.
• Standard OCR uses ocr_engine=tesseract.
• Advanced OCR uses ocr_mode=page, ocr_engine=advanced, and an ocr_output_format of text, markdown, or json.
• Structured table extraction uses extract_tables=true, includes Table in categories, and supports table_format values of markdown, html, or csv.

OCR and batch access depend on the current account plan. See the API guide for the matching API behavior.

Troubleshooting

The server does not start

Run uvx pdf-extractor-mcp in a terminal. If the command is missing, install uv; if Python is too old, install Python 3.10 or later. A client launched from the desktop may have a different executable search path than an interactive shell, so an absolute command path may be needed.

The client shows no tools

Check the JSON syntax, save the correct settings file, and fully restart the client. Confirm that the process stays running and writes protocol messages to standard output rather than a log or interactive prompt.

The server says the API key is missing

The variable name must be PDF_EXTRACTOR_API_KEY inside the MCP server's env object. A shell variable is not always inherited by an app launched from the desktop.

Requests return authentication errors

Create a new token on the Tokens page, replace the configured value, restart the client, and revoke the old token. Tokens begin with pdf-ext_.

A PDF path cannot be opened

Use an absolute path and confirm that the client or its sandbox can read the folder. Do not weaken broad filesystem protections only to test the integration; copy a synthetic test PDF into an approved folder instead.

The package is published at PyPI. More checks are available in Troubleshooting.

Get help or request MCP features

Report a reproducible MCP bug or request an MCP enhancement.

GitHub Issues are public. Remove tokens, local paths, document content, personal information, and client logs that contain private prompts. Use private support when a safe public reproduction is not possible.

Last reviewed: August 21, 2026.