SDK · AI agents

Use PDFluent from Claude, Cursor and other agents

pdfluent-mcp is an MCP server that lets your AI client read, search and fill local PDFs. It runs on your machine and your documents are not uploaded.
Quick start

One command

Run this once. It registers a stdio server named pdfluent in the user configs of Claude Desktop, Claude Code, Cursor and Codex, then tells you to restart the clients. Then ask your client about a PDF in that folder.

uvx pdfluent-mcp setup --root ~/Documents

It needs Python 3.10 or later and uv. uvx downloads the server and the pdfluent package on first use and caches them. --root names the folder the server may read and write in; repeat it for more folders. The 0.3.0 server code passes its own test suite on Windows, macOS and Linux, on Python 3.10 and 3.13.

Install per client

Config for each client

Replace /path/to/documents with the folder your PDFs live in.

Claude Desktop

Add this to claude_desktop_config.json and restart Claude Desktop.

json
{
  "mcpServers": {
    "pdfluent": {
      "command": "uvx",
      "args": ["pdfluent-mcp", "--root", "/path/to/documents"]
    }
  }
}

Claude Code

claude mcp add pdfluent -- uvx pdfluent-mcp --root /path/to/documents

Cursor

Add this to ~/.cursor/mcp.json or the project's .cursor/mcp.json.

json
{
  "mcpServers": {
    "pdfluent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pdfluent-mcp", "--root", "/path/to/documents"]
    }
  }
}

VS Code

From a terminal:

shell
code --add-mcp '{"name":"pdfluent","type":"stdio","command":"uvx","args":["pdfluent-mcp","--root","/path/to/documents"]}'

Codex

Add this to ~/.codex/config.toml.

toml
[mcp_servers.pdfluent]
command = "uvx"
args = ["pdfluent-mcp", "--root", "/path/to/documents"]
Tools

Nine tools

Eight of them only read. fill_form writes a new file and never changes the input. Page numbers are 0-based in every argument and result.
ToolWhat it doesExample prompt
extract_markdownThe document as markdown in reading order: headings, list items and tables. Running heads and page numbers are left out.Summarise ~/Documents/report.pdf.
extract_textThe plain text layer, page by page, each page behind <!-- page N -->.Give me the raw text of pages 0 to 2 of contract.pdf.
extract_tablesOne entry per table with page, rows and header_rows.Pull the tables out of invoice.pdf.
extract_blocksPositioned blocks with kind, text, page, bbox and confidence. Also lists the pages whose text layer is missing.List every heading in manual.pdf with its page.
get_metadataPage count, title, author, dates, PDF version, encryption, form fields, signatures, bookmarks, and pages with no text layer.How many pages does scan.pdf have, and is it encrypted?
searchThe pages that mention a query, with up to three snippets per page.Which pages of policy.pdf mention retention?
list_form_fieldsEvery form field with name, type, value and page.Which fields does application.pdf have?
fill_formFills the named fields and writes a new file. The input is never changed.Fill application.pdf with my name and address, save as application-filled.pdf.
vision_adviceOne entry per page with needs_vision and its reasons.Which pages of scan.pdf need a vision model?
Privacy

Runs on your machine, no upload

The server runs over stdio, one process per client, on the pdfluent Python package. It opens no network listener and uploads nothing. It reads and writes only inside the directories you allow, with --root, with PDFLUENT_MCP_ROOTS, or through the roots your client offers. Symbolic links are resolved before the check, so a link inside a root cannot point outside it. Without any root, the server answers every call with a message saying so.

A root is as wide as the directory it names. If your client offers /, your home folder or a whole drive as a root, the server can reach everything you can read. Start it with --root on the folder your PDFs live in and keep the client's roots narrow.

Licence

Same terms as the SDK

pdfluent-mcp is licensed AGPL-3.0-only or under the PDFluent Commercial Licence, the same as the pdfluent package it runs on. The source is public on GitHub.

Questions and answers

What is pdfluent-mcp?
pdfluent-mcp is an MCP server that lets an AI client read a local PDF as markdown, plain text, tables or positioned blocks, look up its metadata, search it, list its form fields and fill them into a new file. It has nine tools and is built on the PDFluent SDK.
Which AI clients can use it?
Claude Desktop, Claude Code, Cursor, VS Code, Codex and any other MCP client that can start a local stdio server. The setup command registers it in Claude Desktop, Claude Code, Cursor and Codex; VS Code and other clients take the config shown above.
Does it upload my PDFs?
No. The server runs on your machine over stdio, one process per client, with no network listener and no upload. It reads and writes only inside the directories you allow, and without an allowed directory it refuses every call.
What do I need to install it?
Python 3.10 or later and uv. The command uvx pdfluent-mcp downloads the server and the pdfluent package on first use and caches them. The 0.3.0 server code passes its own test suite on Windows, macOS and Linux, on Python 3.10 and 3.13.
Is pdfluent-mcp free?
It is free under the AGPL-3.0, the same terms as the pdfluent SDK it runs on, or you can buy the PDFluent Commercial Licence if you would rather not publish your own source. The source is public on GitHub.
SDK · AI agents

Give your agent the PDFs on your machine.

One command, and the files stay where they are.