PDF Form MCP Server

一个基于 MCP (Model Context Protocol) 的 PDF 表单填写服务，支持获取 PDF 表单字段信息、填充文本和插入图片。

特性

✨ 多语言支持 - 完美支持中文、日文等 Unicode 字符
📝 表单填充 - 支持文本框、复选框、下拉框、单选框
🖼️ 图片插入 - 支持 PNG/JPG 格式图片
⚡ 批量操作 - 一次性填充多个字段
🔧 类型安全 - 使用 TypeScript 和 JSON Schema 验证

安装

方式 1: 使用 npx（推荐）

无需安装，直接使用：

npx pdf-form-mcp

方式 2: 全局安装

npm install -g pdf-form-mcp
pdf-form-mcp

方式 3: 本地开发

git clone <repository-url>
cd pdf-form-mcp
bun install
bun run start

功能特性

1. 获取 PDF 表单字段 (get_pdf_fields)

获取 PDF 文件中所有可填写的表单字段信息，包括：

• 字段名称
• 字段类型（文本框、复选框、下拉框、单选框等）
• 当前值
• 可选项（适用于下拉框和单选框）

参数：

• pdfPath (string): PDF 文件的绝对路径

2. 填充文本字段 (fill_pdf_text)

在 PDF 表单的文本字段中填充文本内容。

参数：

• pdfPath (string): 源 PDF 文件的绝对路径
• outputPath (string): 输出 PDF 文件的绝对路径
• fieldName (string): 要填充的字段名称
• text (string): 要填充的文本内容

3. 插入图片 (fill_pdf_image)

在 PDF 的指定位置插入图片（支持 PNG 和 JPG 格式）。

参数：

• pdfPath (string): 源 PDF 文件的绝对路径
• outputPath (string): 输出 PDF 文件的绝对路径
• imagePath (string): 图片文件的绝对路径
• pageIndex (number): 页面索引（从 0 开始）
• x (number): 图片左下角的 X 坐标
• y (number): 图片左下角的 Y 坐标
• width (number): 图片宽度
• height (number): 图片高度

4. 批量填充字段 (fill_pdf_fields)

批量填充 PDF 表单的多个字段，支持文本框、复选框、下拉框和单选框。

参数：

• pdfPath (string): 源 PDF 文件的绝对路径
• outputPath (string): 输出 PDF 文件的绝对路径
• fields (array): 要填充的字段数组
  • name (string): 字段名称
  • value (string, 可选): 字段值
  • checked (boolean, 可选): 是否选中（仅用于复选框）

使用方法

在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件：

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

添加以下配置：

{
  "mcpServers": {
    "pdf-form": {
      "command": "npx",
      "args": ["-y", "pdf-form-mcp"]
    }
  }
}

重启 Claude Desktop 后即可使用。

在其他 MCP 客户端中使用

任何支持 MCP 协议的客户端都可以使用此服务器：

{
  "mcpServers": {
    "pdf-form": {
      "command": "npx",
      "args": ["-y", "pdf-form-mcp"]
    }
  }
}

或使用全局安装：

{
  "mcpServers": {
    "pdf-form": {
      "command": "pdf-form-mcp"
    }
  }
}

示例使用场景

1. 查看 PDF 表单字段

// 调用 get_pdf_fields 工具
{
  "pdfPath": "/path/to/form.pdf"
}

2. 填充单个文本字段

// 调用 fill_pdf_text 工具
{
  "pdfPath": "/path/to/form.pdf",
  "outputPath": "/path/to/filled-form.pdf",
  "fieldName": "Name",
  "text": "张三"
}

3. 插入签名图片

// 调用 fill_pdf_image 工具
{
  "pdfPath": "/path/to/form.pdf",
  "outputPath": "/path/to/signed-form.pdf",
  "imagePath": "/path/to/signature.png",
  "pageIndex": 0,
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 80
}

4. 批量填充表单

// 调用 fill_pdf_fields 工具
{
  "pdfPath": "/path/to/form.pdf",
  "outputPath": "/path/to/completed-form.pdf",
  "fields": [
    { "name": "Name", "value": "张三" },
    { "name": "Email", "value": "[email protected]" },
    { "name": "AgreeToTerms", "checked": true },
    { "name": "Country", "value": "China" }
  ]
}

技术栈

• Node.js >= 18.0.0
• TypeScript - 类型安全
• pdf-lib - PDF 文档操作
• @modelcontextprotocol/sdk - MCP 协议实现

开发

本地开发

# 克隆仓库
git clone <repository-url>
cd pdf-form-mcp

# 安装依赖
bun install

# 开发模式（自动重启）
bun run dev

# 运行测试
bun test

# 构建
bun run build

发布新版本

使用提供的发布脚本：

./publish.sh

脚本会自动：

1. 运行测试
2. 构建项目
3. 更新版本号
4. 发布到 npm
5. 推送到 Git

注意事项

• 所有文件路径必须使用绝对路径
• 图片仅支持 PNG 和 JPG 格式
• 页面索引从 0 开始计数
• 坐标系统：原点 (0, 0) 在页面左下角
• 支持中文、日文等 Unicode 字符（使用富文本格式）

常见问题

Q: 中文字符无法显示？

A: 本服务已启用富文本格式支持，确保 PDF 阅读器支持 Unicode 字符即可。

Q: 如何获取字段名称？

A: 使用 get_pdf_fields 工具查看 PDF 中所有可用字段。

Q: 图片坐标如何确定？

A: PDF 坐标系原点在左下角，可以先用较大的值测试，然后逐步调整。

贡献

欢迎提交 Issue 和 Pull Request！

License

MIT License - 详见 LICENSE 文件