pdfdancer-mcp

Add PDFDancer to your AI coding assistant

Edit text in any real-world PDF. Even ones you didn't create. PDFDancer edits inbound PDFs like a real document format: paragraphs, lines, glyphs, vectors, forms, plus ML-driven font handling for missing or embedded fonts.

pdfdancer-mcp is a Model Context Protocol (MCP) server that connects PDFDancer to MCP-compatible AI coding assistants so they can write, run, and refactor PDFDancer SDK code inside your projects (TypeScript, Python, and Java). Use it to build and maintain services, workflows, and tooling that transform PDFs you didn’t create. Ideal for ingestion pipelines, document workflows, and AI agents that need to modify PDFs in production.

For Users

Requirements

• Node.js >= v18.0.0
• MCP Client: Cursor, Claude Code, VS Code, Windsurf, Zed, or any other MCP-compatible client

Installation

Add this MCP server to your preferred AI coding assistant. Choose your client below for specific installation instructions.

Option 1: One-Click Installation (Recommended)

Click the button below to install pdfdancer-mcp in Cursor:

Option 2: Manual Configuration

1. Open Cursor Settings
2. Navigate to the "MCP" section
3. Add the following configuration:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Option 1: CLI Command (Recommended)

Run this command in your terminal:

claude mcp add --transport stdio pdfdancer-mcp -- npx -y @pdfdancer/pdfdancer-mcp

Verify installation with: claude mcp list

Option 2: Manual Configuration

Add the following to your Claude Code MCP settings configuration file:

Location: ~/.config/claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

After adding the configuration, restart Claude Code to activate the MCP server.

Option 1: Desktop Extensions (Easiest - Coming Soon)

When available, navigate to Settings > Extensions > Browse extensions and search for "pdfdancer-mcp" for one-click installation.

Option 2: Manual Configuration

Add the following to your Claude Desktop MCP settings configuration file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

After adding the configuration, restart Claude Desktop to activate the MCP server.

Option 1: Using Settings UI (Recommended)

1. Open Windsurf Settings (click the Windsurf icon in bottom right, or Cmd+Shift+P / Ctrl+Shift+P and type "Open Windsurf Settings")
2. Navigate to Advanced Settings > Cascade > Model Context Protocol
3. Click the MCP servers button (hammer icon), then Configure
4. Add the server using the configuration interface

Option 2: Manual Configuration

Edit the mcp_config.json file and add:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

When using MCP-compatible extensions in VS Code:

1. Install an MCP client extension (such as Cline, Roo Code, or similar)
2. Open the extension's settings
3. Add the MCP server configuration:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Option 1: Using AI Assistant (Easiest)

In the Cline chatbot, use this prompt:

install the MCP server named `@pdfdancer/pdfdancer-mcp` for Cline - ensure the mcp settings are updated

Option 2: Using MCP Servers UI

1. Click the MCP Servers icon in Cline's top navigation bar
2. Select "Configure MCP Servers"
3. Browse the MCP marketplace or add manually

Option 3: Manual Configuration

Edit cline_mcp_settings.json:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Option 1: Extension Method (Recommended - If Available)

1. Open Command Palette (search for "zed: extensions")
2. Check the extensions marketplace for "pdfdancer-mcp"
3. Install the extension if available - Zed will guide you through setup

Option 2: Custom Server via UI

1. Open the Agent Panel's Settings view (or use the "agent: open settings" action)
2. In the Context Servers section, click "+ Add Context Server"
3. Enter the server name: pdfdancer-mcp
4. Click Add Server and configure:
   • Command: npx
   • Args: -y @pdfdancer/pdfdancer-mcp

Option 3: Manual Configuration

Open Zed settings (~/.config/zed/settings.json) and add:

{
  "assistant": {
    "version": "2",
    "mcp_servers": [
      {
        "id": "pdfdancer-mcp",
        "command": "npx",
        "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
      }
    ]
  }
}

Verify by checking the indicator dot next to the server name in Agent Panel settings - green means it's running correctly.

Option 1: Easy MCP (Recommended)

Augment Code's "Easy MCP" feature provides one-click integrations for popular tools. Check the Easy MCP panel in settings for quick installation.

Option 2: UI Configuration

1. Open Augment Code settings
2. Navigate to MCP Servers
3. Click "Add Server"
4. Enter:
   • Name: pdfdancer-mcp
   • Command: npx
   • Args: -y @pdfdancer/pdfdancer-mcp

Option 3: Manual Configuration

Edit your Augment Code configuration file:

{
  "augment.advanced": {
    "mcpServers": [{
      "name": "pdfdancer-mcp",
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }]
  }
}

Option 1: Using MCP Settings Panel (Recommended)

1. Click the Roo Code MCP icon
2. Click "Edit Global MCP"
3. Paste the configuration below inside the mcpServers object
4. Save the file

Option 2: Manual Configuration

Edit mcp_settings.json (Global) or .roo/mcp.json (Project-level):

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Note: Global configuration applies across all workspaces, while project-level is specific to your project's root.

Add to your Gemini CLI configuration:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Add to your Qwen Coder MCP settings:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Requirements: IntelliJ IDEA 2025.1+ or other JetBrains IDE with AI Assistant 251.26094.80.5+

Option 1: Import from Claude (Easiest)

1. Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP)
2. Click "Import from Claude"
3. Select the pdfdancer-mcp server from your Claude Desktop configuration

Option 2: Add via Settings UI

1. Open IDE settings (Ctrl+Alt+S or Cmd+,)
2. Navigate to Tools → AI Assistant → Model Context Protocol (MCP)
3. Click "Add Command" or use the Add option
4. Configure:
   • Name: pdfdancer-mcp
   • Command: npx
   • Args: -y @pdfdancer/pdfdancer-mcp

Option 3: Manual Configuration

Add to your MCP configuration:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Note: Version 2025.2+ includes built-in MCP server support for external clients.

Configure in your Amazon Q Developer CLI settings:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Add to Warp's AI configuration:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Configure in your GitHub Copilot CLI settings:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Add to BoltAI MCP configuration:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Configure in Perplexity Desktop settings:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Add to your Docker container configuration:

FROM node:18

RUN npx -y @pdfdancer/pdfdancer-mcp

Or use in docker-compose:

services:
  pdfdancer-mcp:
    image: node:18
    command: npx -y @pdfdancer/pdfdancer-mcp

For any other MCP-compatible client, use the following standard configuration:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"]
    }
  }
}

Consult your client's documentation for the specific location of the MCP configuration file.

Custom Documentation Endpoint (Optional)

If you're using a custom PDFDancer documentation endpoint, you can configure it via environment variable:

{
  "mcpServers": {
    "pdfdancer-mcp": {
      "command": "npx",
      "args": ["-y", "@pdfdancer/pdfdancer-mcp"],
      "env": {
        "PDFDANCER_DOCS_BASE_URL": "https://your-docs-endpoint.com"
      }
    }
  }
}

Available Tools

The MCP server provides the following tools for accessing PDFDancer documentation:

• help – Display comprehensive overview of PDFDancer SDK capabilities with multi-language code samples (TypeScript, Python, Java) demonstrating common PDF manipulation tasks.

• version – Get the current version of the pdfdancer-mcp server.

• search-docs – Search the official PDFDancer SDK documentation by keyword. Returns matching documentation routes with titles, content snippets, and relevance scores (max 10 results). Use this to find information about PDFDancer features, APIs, and usage examples.

• get-docs – Retrieve the full documentation content for a specific route. After finding relevant documentation with search-docs, use this tool to get the complete markdown content including code examples, detailed explanations, and API references.

Typical Workflow

1. Install the server in your MCP-compatible client (Cursor, Claude Code, Windsurf, Zed, etc.).
2. Open a codebase that uses PDFDancer (or ask your assistant to add the SDK).
3. Describe the behavior you want in code – for example: "add a step that redacts email addresses in every inbound PDF", "add a function that moves this header up 20px", or "create a job that stamps a footer on all pages".
4. Let the agent write and refactor the code using the PDFDancer SDKs through this MCP server, then run tests or sample PDFs.
5. Commit and ship your workflow once the code and resulting PDFs behave as expected.

Demo: Using PDFDancer MCP with Claude Code

Once you've installed the PDFDancer MCP server, you can prompt Claude Code to build PDF applications. Here's a real terminal session:

What happened:

1. User prompted: create a typescript project which creates a pdf with the words "Hello World" on it. Use pdfdancer
2. Claude Code searched the PDFDancer documentation using the MCP
3. Created a complete TypeScript project with proper setup
4. Built and ran the project
5. Generated output.pdf with "Hello World" text

The PDFDancer MCP enables Claude Code to instantly provide accurate, up-to-date documentation and code examples without hallucinating APIs.

For Developers

Development

npm install
npm run dev   # starts the server via tsx for quick iteration
npm run build # emits ESM output to dist/
npm run lint  # type-check without emitting files

Publishing to npm

The package is configured to automatically build and lint before publishing:

# Login to npm (first time only)
npm login

# Publish to npm (prepublishOnly script runs automatically)
npm run publish:npm

Or use the standard npm publish command:

npm publish

The prepublishOnly script ensures the package is linted and built before each publish.

Local testing

1. Build the distributable files so the CLI matches the eventual npm artifact:

   npm run build

2. Launch the stdio server exactly as npx would, but pointing to the local package directory:

   npx -y .

3. Alternatively, run the compiled output directly with Node:

   node dist/index.js

4. For the fastest inner loop while editing TypeScript, use:

   npm run dev

Any MCP-compatible client (Claude Desktop, MCP CLI, etc.) can now connect to the running process over stdio.

Configuration

Set PDFDANCER_DOCS_BASE_URL to point to your PDFDancer documentation service endpoint if different from the default. The server defaults to the official PDFDancer documentation service.

Example:

export PDFDANCER_DOCS_BASE_URL=https://your-docs-endpoint.com
npx -y . # or npm run dev