PDFluent

pdfluent-mcp

一个适用于 PDFluent 的 MCP 服务。它可让 Claude Desktop、Claude Code、Cursor、VS Code 及其他任何 MCP 客户端，将本地 PDF 读取为 Markdown、纯文本、表格或带位置信息的块，查询其元数据、搜索内容，并将表单字段填写到新文件中。

它通过标准输入/输出运行，每个客户端使用一个进程，并基于 pdfluent Python 包。你的文档会保留在本机。服务只会在你允许的目录中读取和写入。均衡质量等级需要模型文件；运行 pdfluent models install 可下载一次。你的文档绝不会上传。

工具

工具	返回内容
extract_markdown(path, pages?, quality?)	按阅读顺序排列的 Markdown 文档内容：标题、列表项和表格。省略页眉和页码。quality 为 fast（默认）或 balanced。
extract_text(path, pages?)	逐页返回纯文本层，每页内容前都有 ``。
extract_tables(path, pages?)	tables：每个表格对应一项，包含 page、rows（单元格字符串列表）和 header_rows。
extract_blocks(path, pages?, include_furniture?)	blocks：每项包含 kind、text、page、bbox 和 confidence，适用时还包含 level、ordinal 或表格单元格位置。pages_needing_vision：缺少文本层的页面。
get_metadata(path)	页数、标题、作者、日期、PDF 版本、加密状态、文档是否包含表单字段、签名和书签数量，以及缺少文本层的页面。
search(path, query)	提及 query 的页面，每页最多包含三个摘要片段。
list_form_fields(path)	每个表单字段的 name、type、value 和 page。
fill_form(path, values, out_path, overwrite?)	填写指定字段，并在 out_path 创建新文件。输入文件不会更改；除非 overwrite 为 true，否则拒绝使用已存在的 out_path；如果该路径是符号链接，则始终拒绝。
vision_advice(path)	advice：每页对应一项，包含 needs_vision 及其原因。

所有参数和结果中的页码均从 0 开始。confidence 表示判断块类型的学习模型给出的概率；如果没有模型作出判断，则为 null。null 表示未知，不表示置信度低。

安装

需要 Python 3.10 或更高版本，以及 uv。uvx 会在首次使用时下载服务和 pdfluent，并将其缓存。

uvx pdfluent-mcp --root ~/Documents

或安装到你自己的环境中：

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

允许的根目录

服务不会访问其根目录之外的任何内容。可通过 --root 指定根目录（多个目录可重复指定），也可使用 PDFLUENT_MCP_ROOTS（以 : 分隔；Windows 上使用 ;），或者由客户端提供：Claude Code 会将其工作目录和 --add-dir 指定的目录作为 MCP 根目录发送。如果服务没有从上述任何方式获得根目录，则每次调用都会返回相应提示。检查前会先解析符号链接，因此根目录内的链接无法指向根目录外。

根目录的范围与其指定的目录一样大。如果客户端将 /、~ 或整个驱动器作为 MCP 根目录提供，服务的访问范围就会扩大到用户可读取的所有内容；如果你不希望如此，请使用 --root 将服务限制在存放 PDF 的文件夹，并确保客户端提供的根目录范围较小。

还有三项限制：--max-pages（默认值为 200）限制单次调用返回的页数，因此长文档会通过 pages 分窗口读取（引擎在每个窗口中仍会解析整份文档；此上限限制的是输出，而非处理量）；--max-bytes（默认值为 100 MiB）限制服务打开的文档大小；--max-output-chars（默认值为 200000）限制单次调用返回结果的长度，超过后会截断并给出提示。三项限制也可分别通过 PDFLUENT_MCP_MAX_PAGES、PDFLUENT_MCP_MAX_BYTES 和 PDFLUENT_MCP_MAX_OUTPUT_CHARS 设置。

请将下方的 /path/to/documents 替换为存放 PDF 的目录。

Claude Desktop

添加到 claude_desktop_config.json（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json，Windows： %APPDATA%\Claude\claude_desktop_config.json），然后重启 Claude Desktop：

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

如果 Claude Desktop 找不到 uvx，请在 command 中填写其完整路径（which uvx）。

Claude Code

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

Claude Code 也会将其工作目录作为 MCP 根目录，因此在项目内，只需执行 claude mcp add pdfluent -- uvx pdfluent-mcp。对于团队，可将以下内容放入项目的 .mcp.json：

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

要告知 Claude 何时使用这些工具，请将此仓库中的 skill/pdfluent 复制到 ~/.claude/skills/pdfluent（适用于每个项目），或复制到某个项目中的 .claude/skills/pdfluent。

Cursor

添加到 Cursor （然后更改 /path/to/documents），或添加到 ~/.cursor/mcp.json 或项目的 .cursor/mcp.json：

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

VS Code

在 VS Code 中安装， 或在终端中运行：

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

也可以添加到工作区中的 .vscode/mcp.json（注意键名为 servers）：

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

Codex

添加到 ~/.codex/config.toml：

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

开发

pip install -e ".[test]"
pytest

测试会通过真实的 MCP 客户端，以 stdio 方式启动服务，调用 tests/fixtures 中 PDF 的所有工具，并尝试访问允许的根目录之外的位置。

许可

与其运行所依赖的 pdfluent 包相同：AGPL-3.0-only，或 PDFluent Commercial Licence。请参阅 LICENSE 和 LICENSE-COMMERCIAL。它依赖 mcp（MIT）。