eSign MCP Server

Created By

adamanz7 months ago

MCP server for signing PDF documents with signature images. Built upon signpdf by Charlie DeTar.

Content

eSign MCP Server

An MCP (Model Context Protocol) server that provides tools for signing PDF documents by adding signature images at specified coordinates.

Credits

This MCP server is built upon the excellent signpdf project by Charlie DeTar (cfd@media.mit.edu). The original signpdf utility provides the core PDF signing functionality that this MCP server wraps with a modern MCP interface.

Features

sign_pdf: Add signature images to PDF documents with precise positioning
get_pdf_info: Get PDF metadata including page count and dimensions
Input validation and error handling
Support for PNG and JPG signature images
Optional date stamping
Base64 encoding for file transfer

Tools

sign_pdf

Signs a PDF document by adding a signature image at the specified coordinates.

Parameters:

pdf_data (string): Base64 encoded PDF file content
signature_data (string): Base64 encoded signature image (PNG, JPG)
page_number (int, optional): Page number to sign (1-based indexing, default: 1)
x (float, optional): X coordinate from bottom-left corner in PDF units (default: 100)
y (float, optional): Y coordinate from bottom-left corner in PDF units (default: 100)
width (float, optional): Width of the signature in PDF units (default: 125)
height (float, optional): Height of the signature in PDF units (default: 40)
add_date (bool, optional): Whether to add current date next to signature (default: false)

Returns: Base64 encoded signed PDF content

get_pdf_info

Get information about a PDF document including page count and dimensions.

Parameters:

pdf_data (string): Base64 encoded PDF file content

Returns:

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

Installation

Prerequisites

Python 3.11+
uv package manager (recommended) or pip

Local Installation

Clone or download this repository
Install dependencies:
```
uv pip install -r requirements.txt
```

Running the Server

To run the MCP server:

uv run python mcp_server.py

The server will start with stdio transport by default.

Testing

A test script is provided to verify the server functionality:

uv run python test_server.py

This will:

Create a test PDF document
Generate a test signature image
Test the get_pdf_info tool
Test the sign_pdf tool
Save the signed PDF as test_signed.pdf

Docker Deployment

The server includes Docker support for containerized deployment:

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

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

Smithery Deployment

This server is configured for deployment on Smithery with the included smithery.yaml configuration file.

Configuration Files

Dockerfile: Container build instructions
smithery.yaml: Smithery deployment configuration
requirements.txt: Python dependencies

Usage Examples

Using with Claude Desktop

Install Claude Desktop from claude.ai/download

Clone this repository:

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

Install dependencies:
```
uv pip install -r requirements.txt
```
Configure Claude Desktop by editing your configuration file:

Location of config file:

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

Configuration:

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

Restart Claude Desktop to load the MCP server
Look for the MCP tools - you should see a 🔨 hammer icon indicating available tools

Using with Claude Code

Install Claude Code (if not already installed)

Clone this repository in your project directory:

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

Start the MCP server in your terminal:
```
uv run python mcp_server.py
```
In Claude Code, the MCP server will be automatically detected when running in stdio mode
Use the tools directly in your conversations with Claude Code

Using with Cursor

Install Cursor from cursor.sh

Set up the MCP server by adding it to your project:

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

Configure Cursor to use the MCP server by creating or editing your Cursor MCP configuration
Run the server:
```
uv run python mcp_server.py
```
Access tools through Cursor's AI assistant interface

Alternative: Using without uv

If you prefer using standard pip:

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

Update your configuration to use python instead of uv run python.

Example Tool Calls

Get PDF Info:

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

Sign 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
  }
}

Practical Usage Examples

Once your MCP server is running, you can use natural language to interact with the PDF signing tools:

Example conversations:

Getting PDF Information:

"I have a PDF file. Can you tell me how many pages it has and what the dimensions are?"

The AI will ask you to provide the PDF file, then use the get_pdf_info tool to analyze it.
Signing a PDF:

"I need to sign this contract PDF on the first page. Can you add my signature image in the bottom right corner?"

The AI will use the sign_pdf tool with appropriate coordinates for bottom-right placement.
Multiple signatures:

"Please add my signature to page 2 of this PDF, positioned at coordinates 200, 150, and make it 100x30 pixels. Also add today's date."

The AI will use precise coordinates and enable date stamping.
Getting help with coordinates:

"I want to sign this PDF but I'm not sure where to place the signature. Can you help me understand the coordinate system?"

The AI can explain PDF coordinates and help you choose appropriate values.

Technical Notes

PDF Coordinates

Coordinates use PDF standard units (1/72 inch)
Origin (0,0) is at the bottom-left corner of the page
X increases rightward, Y increases upward

Supported Image Formats

PNG (recommended for transparency support)
JPG/JPEG

File Handling

All file operations use temporary files that are automatically cleaned up
Input validation prevents common errors
Proper error handling with descriptive messages

Dependencies

fastmcp: FastMCP framework for MCP server implementation
pypdf: PDF reading and writing library
reportlab: PDF generation and image placement
pillow: Image processing (dependency of reportlab)

Troubleshooting

Common Issues

"Module not found" errors

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

MCP server not appearing in Claude Desktop
- Check that the path in claude_desktop_config.json is absolute (not relative)
- Restart Claude Desktop after making configuration changes
- Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log (macOS)
"Command not found: uv"
- Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
- Or use regular pip instead: replace uv run python with python

Permission errors

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

PDF signing fails
- Ensure your PDF and signature image are valid
- Check that coordinates are within the page boundaries
- Use get_pdf_info first to understand page dimensions

Getting Help

Check the GitHub Issues for common problems
Run the test script to verify installation: uv run python test_server.py
For Claude Desktop specific issues, check the MCP troubleshooting guide

License

MIT License - This project maintains the same license as the original signpdf project by Charlie DeTar.

Original Project

The core PDF signing functionality is based on the signpdf utility by Charlie DeTar. This MCP server extends that work to provide MCP-compatible tools for modern AI integration.