PDF Kit
AI-powered PDF tools: fill forms via natural language
Open source Repository Open in the app JSON README (API)
About
AI-powered PDF tools: fill forms via natural language
Details
- Kind
- MCP servers
- Topic
- Files & documents
- Publisher
- com.hellobasestation
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.7
- Added
- 2026-08-29 03:01:09
- Updated
- 2026-09-13 03:08:55
- Origin id
com.hellobasestation/pdfkit
README
# 📦 PDF Kit MCP Server
<!-- MCP name format for registry validation -->
<!-- mcp-name: com.hellobasestation/pdfkit -->
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)
1. Install the MCP server via Claude Desktop settings
2. Add to your `claude_desktop_config.json`:
```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)
```bash
npm install -g pdfkit-mcp
```
Then configure in your MCP client.
### Option 3: From Source
```bash
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](https://hellobasestation.com))
## ⚙️ 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):
```json
{
"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):
```bash
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: john@example.com..."
>
> *(Coming soon: "Merge these three PDF files" or "Extract all the email addresses from this PDF")*
### As HTTP Server
Start the server:
```bash
node index.js
# Server runs on http://localhost:4000
```
Expose via ngrok:
```bash
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:
1. Start the MCP server:
```bash
node index.js
```
2. In a separate terminal, run ngrok:
```bash
ngrok http 4000
```
3. ngrok will provide a public URL (e.g., `https://abc123.ngrok.io`)
4. 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
```bash
curl http://localhost:4000/health
```
Response:
```json
{
"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):**
```javascript
{
"name": "basestation.create_autofill_job",
"arguments": {
"instructions": "Fill out the form with: Name: John Doe, Email: john@example.com",
"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`:
```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:
1. Create a new tool file in `tools/` directory
2. Export a `TOOL_DEFINITION` object with the tool schema
3. Export a handler function that implements the tool logic
4. Import and register in `index.js`
Example structure:
```javascript
// 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:
```bash
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](https://modelcontextprotocol.io)
- [BaseStation API Documentation](https://hellobasestation.com)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)