eSign MCP Server

eSign MCP 服务

一个用于签署 PDF 文档的 MCP（Model Context Protocol）服务，可在指定坐标添加签名图片。

致谢

此 MCP 服务基于 Charlie DeTar（[email protected]）出色的 signpdf 项目构建。原始的 signpdf 工具提供了核心 PDF 签名功能，此 MCP 服务在此基础上封装了现代 MCP 接口。

功能

• sign_pdf：在 PDF 文档中以精确位置添加签名图片
• get_pdf_info：获取 PDF 元数据，包括页数和尺寸
• 输入验证和错误处理
• 支持 PNG 和 JPG 签名图片
• 可选添加日期戳
• 使用 Base64 编码传输文件

工具

sign_pdf

通过在指定坐标添加签名图片来签署 PDF 文档。

参数：

• pdf_data (string)：Base64 编码的 PDF 文件内容
• signature_data (string)：Base64 编码的签名图片（PNG、JPG）
• page_number (int, optional)：要签署的页码（从 1 开始计数，默认值：1）
• x (float, optional)：PDF 单位下从左下角起算的 X 坐标（默认值：100）
• y (float, optional)：PDF 单位下从左下角起算的 Y 坐标（默认值：100）
• width (float, optional)：签名的宽度，单位为 PDF 单位（默认值：125）
• height (float, optional)：签名的高度，单位为 PDF 单位（默认值：40）
• add_date (bool, optional)：是否在签名旁添加当前日期（默认值：false）

**返回：**Base64 编码的已签名 PDF 内容

get_pdf_info

获取 PDF 文档的信息，包括页数和尺寸。

参数：

• pdf_data (string)：Base64 编码的 PDF 文件内容

返回：

{
  "num_pages": 1,
  "pages": [
    {
      "page_number": 1,
      "width": 612.0,
      "height": 792.0
    }
  ]
}

安装

先决条件

• Python 3.11+
• uv 包管理器（推荐）或 pip

本地安装

1. 克隆或下载此仓库
2. 安装依赖项：

   uv pip install -r requirements.txt
   

运行服务

运行 MCP 服务：

uv run python mcp_server.py

服务默认将以 stdio 传输方式启动。

测试

提供了测试脚本，用于验证服务功能：

uv run python test_server.py

该脚本将：

1. 创建一个测试 PDF 文档
2. 生成一张测试签名图片
3. 测试 get_pdf_info 工具
4. 测试 sign_pdf 工具
5. 将签署后的 PDF 保存为 test_signed.pdf

Docker 部署

此服务支持使用 Docker 进行容器化部署：

# Build the image
docker build -t pdf-signer-mcp .

# Run the container
docker run -p 8000:8000 pdf-signer-mcp

Smithery 部署

此服务已配置为可通过 Smithery 部署，并包含 smithery.yaml 配置文件。

配置文件

• Dockerfile：容器构建说明
• smithery.yaml：Smithery 部署配置
• requirements.txt：Python 依赖项

使用示例

与 Claude Desktop 配合使用

1. 安装 Claude Desktop，请访问 claude.ai/download
2. 克隆此仓库：

   git clone https://github.com/adamanz/esign-mcp.git
   cd esign-mcp
   

3. 安装依赖项：

   uv pip install -r requirements.txt
   

4. 编辑配置文件以配置 Claude Desktop：

配置文件位置：

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

配置：

{
  "mcpServers": {
    "esign-mcp": {
      "command": "uv",
      "args": [
        "run", 
        "python", 
        "/ABSOLUTE/PATH/TO/esign-mcp/mcp_server.py"
      ]
    }
  }
}

5. 重启 Claude Desktop 以加载 MCP 服务
6. 查找 MCP 工具——应能看到 🔨 锤子图标，表示有可用工具

与 Claude Code 配合使用

1. 安装 Claude Code（如果尚未安装）
2. 在项目目录中克隆此仓库：

   git clone https://github.com/adamanz/esign-mcp.git
   cd esign-mcp
   uv pip install -r requirements.txt
   

3. 在终端中启动 MCP 服务：

   uv run python mcp_server.py
   

4. 在 Claude Code 中，以 stdio 模式运行时会自动检测到 MCP 服务
5. 直接在与 Claude Code 的对话中使用这些工具

在 Cursor 中使用

1. 安装 Cursor，从 cursor.sh 获取
2. 设置 MCP 服务，将其添加到项目中：

   git clone https://github.com/adamanz/esign-mcp.git
   cd esign-mcp
   uv pip install -r requirements.txt
   

3. 配置 Cursor，创建或编辑 Cursor MCP 配置，以使用 MCP 服务
4. 运行服务：

   uv run python mcp_server.py
   

5. 通过 Cursor 的 AI 助手界面访问工具

替代方案：不使用 uv

如果你更喜欢使用标准 pip：

git clone https://github.com/adamanz/esign-mcp.git
cd esign-mcp
pip install -r requirements.txt
python mcp_server.py

更新配置，将 uv run python 替换为 python。

工具调用示例

获取 PDF 信息：

{
  "tool": "get_pdf_info",
  "arguments": {
    "pdf_data": "JVBERi0xLjQK..."
  }
}

签署 PDF：

{
  "tool": "sign_pdf",
  "arguments": {
    "pdf_data": "JVBERi0xLjQK...",
    "signature_data": "iVBORw0KGgoAAAA...",
    "page_number": 1,
    "x": 100,
    "y": 100,
    "width": 125,
    "height": 40,
    "add_date": true
  }
}

实用示例

MCP 服务运行后，你可以使用自然语言与 PDF 签署工具交互：

对话示例：

1. 获取 PDF 信息：

   “我有一个 PDF 文件。你能告诉我它有多少页，以及页面尺寸是多少吗？”

   AI 会请你提供 PDF 文件，然后使用 get_pdf_info 工具进行分析。

2. 签署 PDF：

   “我需要在这份合同 PDF 的第一页签名。你能把我的签名图片放在右下角吗？”

   AI 会使用 sign_pdf 工具，并采用适当的坐标将签名放在右下角。

3. 添加多个签名：

   “请将我的签名添加到这份 PDF 的第 2 页，位置设为坐标 200、150，并将尺寸设为 100x30 像素。另外也添加今天的日期。”

   AI 会使用精确坐标并启用日期戳。

4. 获取坐标帮助：

   “我想在这份 PDF 上签名，但不确定签名应该放在哪里。你能帮我了解坐标系统吗？”

   AI 可以说明 PDF 坐标，并帮助你选择合适的值。

技术说明

PDF 坐标

• 坐标使用 PDF 标准单位（1/72 英寸）
• 原点 (0,0) 位于页面左下角
• X 轴向右递增，Y 轴向上递增

支持的图像格式

• PNG（建议使用，支持透明度）
• JPG/JPEG

文件处理

• 所有文件操作都使用临时文件，并会自动清理
• 输入验证可防止常见错误
• 采用完善的错误处理，并提供详细错误信息

依赖项

• fastmcp：用于实现 MCP 服务的 FastMCP 框架
• pypdf：PDF 读取和写入库
• reportlab：PDF 生成和图像放置库
• pillow：图像处理库（reportlab 的依赖项）

故障排除

常见问题

1. “找不到模块”错误

   # Make sure dependencies are installed
   uv pip install -r requirements.txt
   # Or with pip
   pip install -r requirements.txt
   

2. MCP 服务未显示在 Claude Desktop 中

   • 检查 claude_desktop_config.json 中的路径是否为绝对路径（而非相对路径）
   • 更改配置后重启 Claude Desktop
   • 查看 Claude Desktop 日志：~/Library/Logs/Claude/mcp*.log（macOS）

3. “找不到命令：uv”

   • 安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
   • 或改用常规 pip：将 uv run python 替换为 python

4. 权限错误

   # Make sure the script is executable
   chmod +x mcp_server.py
   

5. PDF 签署失败

   • 确保 PDF 和签名图像有效
   • 检查坐标是否在页面边界内
   • 先使用 get_pdf_info 了解页面尺寸

获取帮助

• 查看 GitHub Issues，了解常见问题
• 运行测试脚本验证安装：uv run python test_server.py
• 如遇到 Claude Desktop 特有问题，请查看 MCP 故障排除指南

许可证

MIT 许可证 - 本项目沿用 Charlie DeTar 的原始 signpdf 项目的许可证。

原始项目

核心 PDF 签署功能基于 Charlie DeTar 的 signpdf 工具。此 MCP 服务扩展了该项目，为现代 AI 集成提供兼容 MCP 的工具。

贡献

1. 使用提供的测试脚本测试你的更改
2. 确保正确指定所有依赖项
3. 根据需要更新文档
4. 遵循现有的代码风格和模式