pdfkit-mcp

📦 PDF Kit MCP Server

An AI-powered Model Context Protocol (MCP) server that enables Claude and other AI assistants to work with PDFs using natural language instructions. Fill forms, merge documents, extract data, and split PDFs - all through simple conversation.

✨ Overview

Transform tedious PDF tasks into simple conversations. Just tell your AI assistant what you need, and let PDF Kit handle the rest.

Current Features:

• 📝 Form Filling: Automatically fill PDF forms with natural language instructions

Coming Soon:

• 🔗 PDF Merging: Combine multiple PDFs into one document
• 📊 Data Extraction: Extract structured data from PDFs
• ✂️ PDF Splitting: Split PDFs by page ranges or criteria

Perfect for:

• 📋 Tax forms and government documents
• 🏢 Business applications and contracts
• 🏥 Medical intake forms
• 📄 Document management and organization
• 📊 Data processing workflows

🚀 Features

• Natural Language Instructions: Describe tasks in plain English
• Intelligent Processing: AI automatically understands and executes PDF operations
• Multiple Transport Options: stdio (Claude Desktop) or HTTP (remote/web)
• Secure API Integration: Built on BaseStation's proven PDF processing API
• Real-time Job Status: Track processing progress with job IDs
• Extensible Architecture: Easy to add new PDF tools and capabilities
• Error Handling: Clear error messages and validation

📦 Installation

Option 1: Via Claude Desktop (Recommended)

• Install the MCP server via Claude Desktop settings
• Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pdfkit": {
      "command": "npx",
      "args": ["pdfkit-mcp"],
      "env": {
        "BASESTATION_API_URL": "https://app.hellobasestation.com",
        "BASESTATION_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Via npm (Global Install)

npm install -g pdfkit-mcp

Then configure in your MCP client.

Option 3: From Source

git clone https://github.com/Base-Station-Inc/pdfkit-mcp.git
cd pdfkit-mcp
npm install

Requirements:

• Node.js v20 or higher
• BaseStation API key (get one here)

⚙️ Configuration

Set these environment variables in your MCP client or hosting environment.

• BASESTATION_API_KEY (required)
  • API key for BaseStation requests.
• BASESTATION_API_URL (optional)
  • Default: https://app.hellobasestation.com
• MAX_PDF_MB (optional)
  • Max allowed decoded PDF size in MB. Default: 15.
• REQUEST_TIMEOUT_MS (optional)
  • Timeout for outbound API requests. Default: 15000.
• PORT (optional, HTTP mode only)
  • HTTP server port. Default: 4000.

Example (Claude Desktop, stdio via npx):

{
  "mcpServers": {
    "pdfkit": {
      "command": "npx",
      "args": ["-y", "pdfkit-mcp"],
      "env": {
        "BASESTATION_API_KEY": "<your-api-key>",
        "BASESTATION_API_URL": "https://app.hellobasestation.com",
        "MAX_PDF_MB": "15",
        "REQUEST_TIMEOUT_MS": "15000"
      }
    }
  }
}

Example (HTTP mode, local):

export BASESTATION_API_KEY=your_api_key
export PORT=4000
npm run start:http

🎯 Quick Start

With Claude Desktop

Once installed, simply ask Claude:

"Fill out this PDF form with the following information: Name: John Doe, Email: [e-mail]..."

(Coming soon: "Merge these three PDF files" or "Extract all the email addresses from this PDF")

As HTTP Server

Start the server:

node index.js
# Server runs on http://localhost:4000

Expose via ngrok:

ngrok http 4000

The server will output:

PDF Kit MCP server running on http://localhost:4000
MCP endpoint: http://localhost:4000/mcp
Health check: http://localhost:4000/health

Run 'ngrok http 4000' to expose this server

Exposing with ngrok

To make your MCP server accessible from external applications:

• Start the MCP server:

node index.js

• In a separate terminal, run ngrok:

ngrok http 4000

• ngrok will provide a public URL (e.g., https://abc123.ngrok.io)

• Use the MCP endpoint at:

https://abc123.ngrok.io/mcp

Endpoints

• /mcp - Main MCP endpoint for protocol communication
• /health - Health check endpoint (returns server status)

Health Check Example

curl http://localhost:4000/health

Response:

{
  "status": "ok",
  "name": "pdfkit-mcp",
  "version": "1.0.7"
}

Available Tools

basestation.create_autofill_job

Creates a BaseStation autofill job for PDF form filling.

Parameters:

• instructions (string, required): Natural language instructions for how to fill the form
• formFile (string, required): Base64-encoded PDF file to fill
• callbackUrl (string, optional): Optional callback URL for job completion notification

Returns:

• job_id: The BaseStation job ID
• upload_page_url: URL to the upload page for the job
• instructions_summary: Parsed summary of the instructions

Example Usage (from MCP client):

{
  "name": "basestation.create_autofill_job",
  "arguments": {
    "instructions": "Fill out the form with: Name: John Doe, Email: [e-mail]",
    "formFile": "<base64-encoded-pdf>",
    "callbackUrl": "https://myapp.com/webhook"
  }
}

Architecture

┌─────────────────┐
│   MCP Client    │
│ (e.g., Claude)  │
└────────┬────────┘
         │
         │ HTTP/MCP Protocol
         │
         ▼
┌─────────────────┐
│  MCP Server     │
│  (index.js)     │
└────────┬────────┘
         │
         │ Imports & Executes
         │
         ▼
┌─────────────────┐        ┌──────────────────┐
│  Tool Handler   │───────▶│  BaseStation API │
│(basestation.js) │        │  (External)      │
└─────────────────┘        └──────────────────┘

File Structure

Doc-Base-Station-MCP/
├── index.js              # Main MCP server (HTTP transport)
├── tools/
│   └── basestation.js    # BaseStation tool definition and handler
├── package.json          # Node.js dependencies
├── README.md            # This file
└── docs/                # Internal guides
    ├── LAUNCH_CHECKLIST.md
    ├── PUBLISHING.md
    └── ASSETS_NEEDED.md

Dependencies

• @modelcontextprotocol/sdk - Official MCP TypeScript SDK
• express - Web framework for HTTP server (v5)
• node-fetch - HTTP client for API calls

Development

Project Configuration

The project uses ES modules. Key configuration in package.json:

{
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.20.1",
    "node-fetch": "^3.3.2",
    "express": "^5.1.0"
  }
}

Adding New Tools

To add new tools to the MCP server:

• Create a new tool file in tools/ directory
• Export a TOOL_DEFINITION object with the tool schema
• Export a handler function that implements the tool logic
• Import and register in index.js

Example structure:

// tools/mytool.js
export const TOOL_DEFINITION = {
  name: "my.tool",
  description: "Description of what the tool does",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "Parameter description" }
    },
    required: ["param1"]
  }
};

export async function handleMyTool(args) {
  // Implementation
  return {
    content: [{ type: "text", text: "Result" }]
  };
}

Troubleshooting

Port Already in Use

Change the port using the PORT environment variable:

PORT=8080 node index.js

Connection Issues with ngrok

• Ensure the MCP server is running before starting ngrok
• Check that ngrok is pointing to the correct port
• Verify firewall settings allow incoming connections

License

MIT

Resources

• Model Context Protocol Documentation
• BaseStation API Documentation
• MCP TypeScript SDK