pdfluent-mcp

confidence is the probability of the learned model that decided a block's kind; it is null where no model decided it, and null means unknown, not low.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json.

If Claude Desktop does not find uvx, write its full path (which uvx) in command.

Claude Code also offers its working directory as an MCP root, so inside a project claude mcp add pdfluent -- uvx pdfluent-mcp is enough. For a team, put this in the project's .mcp.json:

{
  "mcpServers": {
    "pdfluent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pdfluent-mcp"]
    }
  }
}

To tell Claude when to reach for these tools, copy skills/pdfluent from this repository to ~/.claude/skills/pdfluent (every project) or to .claude/skills/pdfluent in one project.

Or add to .vscode/mcp.json in the workspace (note the key is servers):

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

• --root DIR (repeatable) is added to the saved command for each directory you name, for example uvx pdfluent-mcp setup --root ~/Documents.
• --dry-run shows what would change and writes nothing.
• Before it replaces a config file, setup saves the previous file next to it as <name>.pdfluent-backup-<timestamp> and prints the path.
• --client claude-desktop|claude-code|cursor|codex limits it to some clients (repeatable).
• uvx pdfluent-mcp uninstall (or setup --uninstall) removes only the pdfluent entry, and only when it was written by pdfluent-mcp (or with --force). It does not remove the Python package.

Close the clients before you run setup or uninstall. Files are replaced atomically, but no portable call lets setup detect a client that saves the same file in the last instant; a save in that gap can be lost, and where hard links are unavailable the backup is a plain copy and the gap is wider.

Setup keeps unrelated settings and servers, preserves TOML comments, and refuses malformed configs and symbolic links. A different existing pdfluent entry is left alone unless you pass --force (SETUP-003). The saved launcher uses the absolute uvx path when found, otherwise the current Python interpreter, which must stay installed (SETUP-004).

Config files used: Claude Desktop's platform config (see above), Claude Code's ~/.claude.json, Cursor's ~/.cursor/mcp.json, and Codex's ~/.codex/config.toml (CODEX_HOME is respected).

pip install pdfluent-mcp
pdfluent-mcp --root ~/Documents

The server touches nothing outside its roots. Give them with --root (repeat for more than one), with PDFLUENT_MCP_ROOTS (:-separated, ; on Windows), or let the client offer them: Claude Code sends its working directory and --add-dir directories as MCP roots. A server with no root from any of these answers every call with a message saying so. Symlinks are resolved before the check, so a link inside a root cannot point outside it.

A root is as wide as the directory it names. A client that offers /, ~ or a drive as an MCP root widens the server to everything the user can read; if that is not what you want, start the server with --root on the folder your PDFs live in and keep the client's roots narrow.

Three more limits: --max-pages (default 200) is how many pages one call returns, so a long document is read in windows through pages (the engine still parses the whole document for every window; the cap bounds the output, not the work); --max-bytes (default 100 MiB) is the largest document the server opens; --max-output-chars (default 200000) is the longest result one call returns, after which it is cut and says so. All three also read from PDFLUENT_MCP_MAX_PAGES, PDFLUENT_MCP_MAX_BYTES and PDFLUENT_MCP_MAX_OUTPUT_CHARS.

The repository is also a Claude plugin (.claude-plugin/plugin.json). It bundles the pdfluent skill from skills/ and starts the local MCP server with uvx pdfluent-mcp==0.3.0 over stdio, so the plugin runs one pinned PyPI package and nothing else. A local MCP server loads in Claude Code and in Cowork sessions on your computer; chat on claude.ai ignores it.

What the plugin does with data: the server reads PDFs only inside the directories you allow, and writes only the new file that fill_form creates there. It stores nothing, keeps no data after a call returns, and sends nothing to any other service. The one download is the pdfluent package and, if you choose the balanced tier, the model files from pdfluent models install. The plugin is not aimed at people under 18.

pip install -e ".[test]"
pytest

The tests start the server over stdio with a real MCP client, call every tool on the PDFs in tests/fixtures, and try to step outside the allowed roots.