@agent2pdf/mcp-server

Official MCP (Model Context Protocol) stdio Server for Agent2PDF with auto-polling support.

This MCP Server acts as a bridge between MCP clients (like Claude Desktop, Cursor) and the Agent2PDF async job API. It automatically handles job creation, polling, and returns a direct download URL when the PDF is ready, providing a "pseudo-synchronous" experience.

Note: Agent2PDF also provides an HTTP MCP endpoint (POST https://api.agent2pdf.com/api/v1/mcp) for agents that cannot run a local Node process. The HTTP endpoint returns job_id only — agents must poll manually. This stdio server is recommended for the best experience.

Features

• 🚀 Auto-polling: generate_pdf automatically polls job status and returns download_url directly
• 📦 Zero-config: Works out of the box with npx
• 🔄 Seven tools: generate_pdf, list_available_templates, get_job_status, get_branding, upload_logo, remove_logo, submit_feedback
• ⚡ Fast: Typical wait time: 5-30 seconds
• 🔀 Pseudo-synchronous: No manual polling needed — just call generate_pdf and get the download URL

Installation

Using npx (Recommended)

No installation needed! Use directly with npx:

npx @agent2pdf/mcp-server

Local Installation

npm install -g @agent2pdf/mcp-server

Check version

From a directory outside the repo (e.g. /tmp), you can confirm the installed version:

npx @agent2pdf/mcp-server --version

Configuration

Note: The server connects to the production API (https://api.agent2pdf.com/api/v1) by default. To use the dev environment, set the AGENT2PDF_API_BASE environment variable.

Claude Desktop

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "agent2pdf": {
      "command": "npx",
      "args": ["@agent2pdf/mcp-server"],
      "env": {
        "AGENT2PDF_API_KEY": "your-api-key-here"
      }
    }
  }
}

For dev environment:

{
  "mcpServers": {
    "agent2pdf": {
      "command": "npx",
      "args": ["@agent2pdf/mcp-server"],
      "env": {
        "AGENT2PDF_API_KEY": "your-dev-api-key",
        "AGENT2PDF_API_BASE": "https://agent2pdf-api-ue3hnvqp6q-de.a.run.app/api/v1"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "agent2pdf": {
      "command": "agent2pdf-mcp",
      "env": {
        "AGENT2PDF_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to your Cursor settings (.cursor/mcp.json or similar):

{
  "mcpServers": {
    "agent2pdf": {
      "command": "npx",
      "args": ["@agent2pdf/mcp-server"],
      "env": {
        "AGENT2PDF_API_KEY": "your-api-key-here"
      }
    }
  }
}

Getting Your API Key

1. Sign in to Agent2PDF Dashboard
2. Go to Settings → API Keys
3. Create a new API key
4. Copy the key and add it to your MCP configuration

Available Tools

generate_pdf

Generate a PDF from Markdown content. This tool automatically handles the async job process (creates job → polls every 3s → returns download URL when ready). Typical wait: 5–30 seconds.

Arguments:

• markdown (required): The document body in Markdown format
• template_type (optional): Template type (general, tech_spec, invoice, report, resume, letter, meeting). Defaults to general
• title (optional): Document title. Defaults to "Untitled"
• author (optional): Author or company name
• template_id (optional): Custom template ID if using a saved template
• use_logo (optional): Whether to include the company logo in the PDF. Defaults to user settings (true if a logo is uploaded)
• heading_numbering (optional): Heading numbering style. none (default), 1.1 (hierarchical, recommended for tech_spec), 1. (flat, recommended for report), 1.1.1 (deep hierarchical). Manually numbered headings are auto-stripped.

Example:

Generate a PDF with markdown "# Hello\n\nWorld", title "Test Document", template_type "general"

list_available_templates

Get a list of available built-in PDF templates with descriptions and recommended use cases.

Arguments: None

Example:

List available templates

get_job_status

Check the status of an async PDF job. Useful for manual polling.

Arguments:

• job_id (required): The job ID returned by generate_pdf or POST /api/v1/jobs

Example:

Check job status for job_id "abc123"

get_branding

Get current branding settings: company name, logo status, colors, font, and watermark. Use this to check whether a logo is already uploaded before generating a PDF.

Arguments: None

Example:

Show my current branding settings

upload_logo

Upload or replace the company logo used in PDF headers and cover pages. Provide either a public image URL or a base64-encoded image. PNG/JPG/SVG/WebP, max 2 MB. Min 128×128px, max 2048×2048px. Max aspect ratio 5:1. Recommended: horizontal logo ~600×200px, transparent PNG. The logo will appear on all future PDFs when use_logo is enabled (default).

Arguments:

• logo_url (optional): Public URL of the logo image to download and store
• logo_base64 (optional): Base64-encoded image, optionally as a data URI (e.g. data:image/png;base64,...)

Provide exactly one of logo_url or logo_base64.

Example:

Upload my company logo from URL "https://example.com/logo.png"

remove_logo

Remove the current company logo. PDFs generated after this will show the company name instead of a logo.

Arguments: None

Example:

Remove the current logo

submit_feedback

Submit feedback about Agent2PDF service. Best practice: call this after every PDF generation session to report quality, suggest improvements, or flag issues. Even a short note helps.

Arguments:

• title (required): Brief summary of your feedback
• category (optional): bug, feature_request, template_request, usability, general (default)
• rating (optional): 1–5 satisfaction rating
• body (optional): Detailed description
• job_id (optional): Related job ID if applicable
• template_type (optional): Related template type if applicable

Example:

Submit feedback: title "Great PDF quality", category "general", rating 5, body "The tech_spec template works perfectly for API docs."

How It Works

1. Job Creation: When generate_pdf is called, the server creates an async job via POST /api/v1/jobs
2. Auto-polling: The server polls GET /api/v1/jobs/{job_id} every 3 seconds
3. Completion: When the job status is completed, it returns the download URL
4. Error Handling: If the job fails or times out (~2 min), it returns an error message
5. Branding: get_branding, upload_logo, and remove_logo manage branding via GET/POST/DELETE /api/v1/settings/logo

stdio Server vs HTTP Endpoint

| Aspect | This stdio Server | HTTP Endpoint (/api/v1/mcp) | |--------|-------------------|-------------------------------| | generate_pdf returns | download_url directly | job_id only (manual polling needed) | | Polling | Automatic (internal) | Agent calls get_job_status in a loop | | Requires local Node | Yes (npx or global install) | No | | MCP protocol | Full (@modelcontextprotocol/sdk) | Simplified (tools/list + tools/call only) | | Best for | Claude Desktop, Cursor, local agents | Cloud agents, serverless environments |

For the HTTP endpoint, see: https://agent2pdf.com/docs/api.md

Development

Prerequisites

• Node.js >= 18
• pnpm (recommended) or npm

Setup

# Install dependencies
pnpm install

# Build
pnpm build

# Development mode (watch)
pnpm dev

Local Testing

自動化測試腳本

使用內建的測試腳本快速驗證所有功能：

# 設定 API Key
export AGENT2PDF_API_KEY="your-api-key"

# 執行測試
npm test

# 或直接執行
node test-mcp-server.js

測試腳本會自動測試：

• ✅ 環境變數檢查
• ✅ 列出可用模板
• ✅ 建立 PDF Job
• ✅ 輪詢 Job 狀態直到完成
• ✅ MCP Server 基本連線

手動測試

# Link globally for testing
pnpm link --global

# Then use in Claude Desktop config
{
  "mcpServers": {
    "agent2pdf": {
      "command": "agent2pdf-mcp",
      "env": {
        "AGENT2PDF_API_KEY": "your-test-key"
      }
    }
  }
}

License

MIT

Support

• Documentation: https://agent2pdf.com/docs
• API Reference: https://agent2pdf.com/docs/api
• Issues: GitHub Issues