Castpdf MCP Server

CastPDF MCP server

The official Model Context Protocol server for CastPDF. It lets AI agents (Claude, Cursor and other MCP clients) list your PDF templates, create PDFs and EU e-invoices, and look up documents, using your CastPDF API key.

Documents are test documents by default (watermarked, not counted against your plan). The agent only makes a live document when you explicitly ask for one, and a cpdf_test_... key can never make live documents at all. Start with a test key.

Tools

Download links are signed and expire (see expires_at); the agent shares the link, the file itself is not sent through the conversation.

Setup

You need Node.js 20 or newer and a CastPDF API key (dashboard > API keys). The server reads the key from the CASTPDF_API_KEY environment variable.

Claude Desktop

Settings > Developer > Edit Config, then add to claude_desktop_config.json:

{
  "mcpServers": {
    "castpdf": {
      "command": "npx",
      "args": ["-y", "@castpdf/mcp"],
      "env": { "CASTPDF_API_KEY": "cpdf_test_..." }
    }
  }
}

Restart Claude Desktop. On Windows, if npx is not found, use "command": "cmd" and "args": ["/c", "npx", "-y", "@castpdf/mcp"].

Claude Code

claude mcp add castpdf --env CASTPDF_API_KEY=cpdf_test_... -- npx -y @castpdf/mcp

Add --scope user to use it in every project. Check it with claude mcp list or /mcp inside Claude Code.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "castpdf": {
      "command": "npx",
      "args": ["-y", "@castpdf/mcp"],
      "env": { "CASTPDF_API_KEY": "cpdf_test_..." }
    }
  }
}

Do not commit a file that contains your key.

Other clients

Any MCP client that starts stdio servers works with the command npx -y @castpdf/mcp and the environment variable CASTPDF_API_KEY.

Streamable HTTP

For clients that connect over HTTP, or to run one shared server:

CASTPDF_API_KEY=cpdf_test_... npx -y @castpdf/mcp --http --port 3000
# MCP endpoint: http://127.0.0.1:3000/mcp   health check: http://127.0.0.1:3000/health

Every request to that endpoint uses the server's API key, so:

• By default it listens on 127.0.0.1 only and accepts only localhost, 127.0.0.1 and [::1] as Host header (DNS rebinding protection) and no browser Origin.
• Set CASTPDF_MCP_AUTH_TOKEN to require Authorization: Bearer <token> on every request. It is required to listen on any other interface (--host 0.0.0.0). Put a TLS-terminating proxy in front of it, and list the public host name in CASTPDF_MCP_ALLOWED_HOSTS.
• The server is stateless (no sessions, POST only), so it can run behind a load balancer.

Example client config for HTTP (Claude Code):

claude mcp add --transport http castpdf http://127.0.0.1:3000/mcp

Configuration

Example prompts

• "Which CastPDF templates do I have?"
• "Make a test PDF of the Invoice template for Ada Lovelace, 3 hours of consulting at 120 EUR."
• "Create a ZUGFeRD invoice from Muster GmbH (DE123456789, Berlin) to Kunde AG, Hamburg: 8 hours consulting at 95 EUR, 19 % VAT, payable within 14 days to IBAN DE02 1203 0000 0000 2020 51."
• "Did my last document fail? Why?"

Use as a library

import { createServer } from '@castpdf/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createServer({ apiKey: process.env.CASTPDF_API_KEY! });
await server.connect(new StdioServerTransport());

Version history

• 0.1.0: first release.

License

MIT