Using POP from an AI assistant (MCP)

Goal

Generate, submit, and check SdI, PEPPOL, KSeF, ZUGFeRD, and PDF invoices, plus sync documents to Zoho, directly from an AI assistant (e.g. Claude Desktop) via the official MCP server (@getpopapi/pop-mcp), without calling the REST API manually.

This guide covers the local install (Node.js, stdio). If you’d rather connect your assistant without installing anything, there’s also a remote MCP server already live — see mcp-remote.

Prerequisites

• Node.js >= 18.
• A valid POP license_key (see get-your-license-key) — if you don’t have an account yet, you can also get one through the headless flow (see api/onboarding), without going through the browser login.
• For SdI/PEPPOL submission: an active integration on your POP account. No minimum plan: sending is available on every plan, including Free, using credits.

Installation

npm install -g @getpopapi/pop-mcp

Alternatively, from source: clone the repository, npm install, npm run build, then point your client at the generated dist/cli.js file.

Configuration

The license_key is passed as an environment variable, never as a call parameter:

export POP_API_KEY=your_license_key

Optional, to use the sandbox environment: export POP_ENVIRONMENT=staging.

Connecting Claude Desktop

Add to the configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, equivalent paths on Windows/Linux):

{
  "mcpServers": {
    "pop": {
      "command": "pop-mcp",
      "env": { "POP_API_KEY": "your_license_key" }
    }
  }
}

Available tools (11)

• Creation — pop_create_sdi_invoice (FatturaPA XML, optional SdI submission), pop_create_peppol_invoice (UBL 2.1, optional PEPPOL submission), pop_create_ksef_invoice (Polish FA(3) XML, optional KSeF submission), pop_create_zugferd_invoice (PDF/XML/hybrid-PDF bundle), pop_create_pdf_invoice (PDF with optional email delivery, up to 3 recipients).
• Zoho sync — pop_sync_zoho_document: syncs an invoice or credit note to Zoho Books/Invoice via the account’s native connector; by default it first checks the Zoho connector is active and connected (GET /integration/zoho/status), failing with a clear error instead of letting the sync fail on Zoho’s side.
• Status and retrieval — pop_get_invoice_status (SdI notifications), pop_get_peppol_document, pop_get_sdi_document.
• Validation and preservation — pop_verify_sdi_document, pop_preserve_document (long-term legal archival). None of these require a minimum plan anymore.

Every tool calls the same REST routes already documented in api/sdi, api/peppol, api/ksef, api/zugferd, api/pdf, and api/zoho — the MCP server doesn’t introduce a different API contract, it only translates the assistant’s requests into HTTP calls to POP.

Verify

Ask the assistant something like “Create a FatturaPA invoice for 1000€ + 22% VAT to Rossi SRL (VAT IT12345678901)”: if the setup is correct, the tool returns the generated XML (or a readable error, with cause and affected field).

Common errors

• unauthorized_user — POP_API_KEY missing or invalid: check it under Account > API on popapi.io.
• integration_inactive — SdI or PEPPOL isn’t active on the account: complete activation before using submit_to_sdi/submit_to_peppol.
• pop_api_email_limit — more than 3 email recipients on pop_create_pdf_invoice: reduce to a maximum of 3.
• pop_preserve_document called at the wrong time — only call it after pop_get_invoice_status returns status RC (Ricevuta di Consegna) or MC (Mancata Consegna), not for other statuses.
• “Zoho integration is not active for this account” — returned by pop_sync_zoho_document before even calling Zoho, if the native connector isn’t active/connected: complete activation from the POP account panel (see guides/integrations/zoho).

Related configuration

For the full data contract (data structure, required fields per document type), see api/overview and the channel-specific pages (api/sdi, api/peppol, api/ksef, api/zugferd, api/pdf, api/zoho).