pop-mcp

# pop-mcp

MCP (Model Context Protocol) server for **POP** — enabling LLMs to generate, submit, and manage Italian e-invoices (FatturaPA/SdI), Peppol invoices, and PDF invoices directly from AI assistants.

> **npm:** `@getpopapi/pop-mcp`

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green)](https://nodejs.org/)

---

## What is POP?

[POP](https://popapi.io) is a cloud service for electronic invoice generation and delivery, supporting:

- 🇮🇹 **Italian e-invoicing (FatturaPA/SdI)** — compliant with D.Lgs. 127/2015
- 🇪🇺 **Peppol** — pan-European cross-border B2B invoicing (UBL 2.1)
- 📄 **PDF invoices** — branded, with email delivery
- ✅ **Validation** — fiscal codes, VAT numbers, document pre-submission checks
- 🗄️ **Preservation** — Italian legal archival (conservazione sostitutiva)

---

## Tools Available (8 total)

### Invoice Creation
| Tool | Endpoint | Plan |
|------|----------|------|
| `pop_create_sdi_invoice` | POST `/create-xml` | Any |
| `pop_create_peppol_invoice` | POST `/create-ubl` | Any (Basic+ to submit) |
| `pop_create_pdf_invoice` | POST `/create-pdf` | Any (Basic+ for email) |

### Status & Retrieval
| Tool | Endpoint | Plan |
|------|----------|------|
| `pop_get_invoice_status` | POST `/sdi-via-pop/document-notifications` | Any |
| `pop_get_peppol_document` | POST `/peppol/document-get` | Basic+ |
| `pop_get_sdi_document` | POST `/sdi-via-pop/document-get` | Growth+ |

### Validation & Advanced SdI
| Tool | Endpoint | Plan |
|------|----------|------|
| `pop_verify_sdi_document` | POST `/sdi-via-pop/document-verify` | Growth+ |
| `pop_preserve_document` | POST `/sdi-via-pop/document-preserve` | Growth+ |

---

## Prerequisites

- Node.js >= 18
- A [POP](https://popapi.io) license key
- For SdI/Peppol submission: active integration on your POP account (Basic/Growth plan)

---

## Authentication

### Get Your License Key

> **New to POP?** Visit [popapi.io](https://popapi.io) to create your account and get your license key.

API-only users can activate their account and obtain a `license_key` with this flow:

1. Open [https://popapi.io/otp-login/](https://popapi.io/otp-login/)
2. Enter your email address
3. Receive a one-time password (OTP) by email and enter it
4. Complete the configuration wizard
5. Open [https://popapi.io/](https://popapi.io/) → **Account > API**
6. Copy the default generated `license_key`

### Key Management

- Your account includes one default `license_key`, visible under **Account > API**
- You can generate additional keys linked to the same account from that same page
- Every `license_key` must be treated as a secret credential — do not commit it to source control

### Recommended First Steps

1. Get your `license_key`
2. Test it with `GET /account-profile`
3. Send one document-generation request with a real payload
4. Add optional delivery integrations only after local generation works

---

## Installation

### From npm (recommended)

```bash
npm install -g @getpopapi/pop-mcp
```

### From Source

```bash
git clone https://github.com/getpopapi/pop-mcp
cd pop-mcp
npm install
npm run build
```

---

## Configuration

Set your POP license key as an environment variable:

```bash
export POP_API_KEY=your_license_key_here
```

Optional — use the staging environment:

```bash
export POP_ENVIRONMENT=staging
```

---

## Claude Desktop Setup

Add to your `claude_desktop_config.json`:

**If installed from npm:**

```json
{
  "mcpServers": {
    "pop": {
      "command": "pop-mcp",
      "env": {
        "POP_API_KEY": "your_license_key_here"
      }
    }
  }
}
```

**If running from source:**

```json
{
  "mcpServers": {
    "pop": {
      "command": "node",
      "args": ["/path/to/pop-mcp/dist/index.js"],
      "env": {
        "POP_API_KEY": "your_license_key_here"
      }
    }
  }
}
```

**Config file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

---

## Tool Reference

The `license_key` is always injected automatically from `POP_API_KEY` — never pass it manually.

### `pop_create_sdi_invoice`

Generate an Italian FatturaPA XML document. Optionally submit it to the SdI (Sistema di Interscambio).

**MCP inputs:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | ✅ | Full invoice data (see Invoice Data Structure) |
| `submit_to_sdi` | boolean | — | Set `true` to submit to SdI. Requires Growth+ plan with active SdI integration. Default: `false` |
| `integration` | object | — | Override integration config. Overrides `submit_to_sdi` if set. |
| `environment` | string | — | Target environment (e.g. `"sandbox"`) |

**Integration options for `integration.use`:**
- `"sdi-via-pop"` or `"sdi"` — Submit via POP SdI
- `"pop-to-webhook"` — Deliver to a webhook (requires `id`)
- `"fatture-in-cloud"` — Deliver to Fatture in Cloud

**API payload sent:**

```json
{
  "license_key": "YOUR_LICENSE_KEY",
  "user_agent": "pop-mcp",
  "user_agent_version": "1.0.0",
  "data": { "...invoice fields..." },
  "integration": { "use": "sdi-via-pop", "action": "create" }
}
```

> `integration` is omitted when `submit_to_sdi` is `false` and no override is provided (XML-only generation).

---

### `pop_create_peppol_invoice`

Generate a Peppol UBL 2.1 document. Optionally submit it to the Peppol network.

**MCP inputs:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | ✅ | Full invoice data. `customer_type` must be `"company"` or `"freelance"` |
| `submit_to_peppol` | boolean | — | Set `true` to submit to the Peppol network. Requires Basic+ plan. Default: `false` |
| `integration` | object | — | Override integration config |
| `environment` | string | — | Target environment |

**Integration options for `integration.use`:**
- `"peppol-via-pop"` or `"peppol"` — Submit via POP Peppol
- `"pop-to-webhook"` — Deliver to a webhook (requires `id`)

**API payload sent:**

```json
{
  "license_key": "YOUR_LICENSE_KEY",
  "user_agent": "pop-mcp",
  "user_agent_version": "1.0.0",
  "data": { "...invoice fields..." },
  "integration": { "use": "peppol-via-pop", "action": "create" }
}
```

---

### `pop_create_pdf_invoice`

Generate a branded PDF invoice. Optionally email it to up to 3 recipients.

**MCP inputs:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | ✅ | Invoice data. Must include `data.pdf` for PDF-specific settings |
| `send_email` | boolean | — | Set `true` to email the PDF (requires `data.pdf.email_invoice`, Basic+ plan). Default: `false` |
| `environment` | string | — | Target environment |

**`data.pdf` fields:**

| Field | Description |
|-------|-------------|
| `doc_type_title` | Title shown on document (e.g. `"Invoice"`, `"Receipt"`) |
| `logo_url` | Company logo URL (HTTPS) |
| `head.store_info_address` | Supplier address string in header |
| `head.billing[]` | Customer billing address array |
| `head.shipping[]` | Shipping address array (optional) |
| `email_invoice.to` | Up to 3 recipient email addresses |
| `email_invoice.from` | Reply-to address |
| `footer_text` | Custom footer message |
| `total_tax` | Total tax amount as string |

**API payload sent:**

```json
{
  "license_key": "YOUR_LICENSE_KEY",
  "user_agent": "pop-mcp",
  "user_agent_version": "1.0.0",
  "data": {
    "...invoice fields...",
    "pdf": {
      "doc_type_title": "Invoice",
      "logo_url": "https://example.com/logo.png",
      "head": { "store_info_address": "Via Roma 1, 00100 Roma IT", "billing": [] },
      "total_tax": "22.00",
      "email_invoice": { "to": ["customer@example.com"] }
    }
  }
}
```

---

### `pop_get_invoice_status`

Retrieve the SdI processing status and notifications for a submitted invoice.

**MCP inputs:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string (UUID) | ✅ | Invoice UUID returned by `pop_create_sdi_invoice` when `submit_to_sdi=true` |
| `response_format` | `"markdown"` \| `"json"` | — | Output format. Default: `"markdown"` |
| `environment` | string | — | Target environment |

**API payload sent:**

```json
{
  "license_key": "YOUR_LICENSE_KEY",
  "integration": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
}
```

**SdI notification statuses:** `pending` · `accepted` · `rejected` · `delivery`

> SdI processing is asynchronous and can take minutes to hours. Retry if no notifications are returned yet.

---

### `pop_get_peppol_document`

Retrieve a Peppol document from the network by UUID.

**MCP inputs:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string (UUID) | ✅ | Peppol document UUID from `pop_create_peppol_invoice` |
| `zone` | string (2 chars) | — | Country code of the Peppol access point (e.g. `"BE"` for Belgium). Required for some regions. |
| `response_format` | `"markdown"` \| `"json"` | — | Output format. Default: `"markdown"` |
| `environment` | string | — | Target environment |

**API payload sent:**

```json
{
  "license_key": "YOUR_LICENSE_KEY",
  "integration": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "zone": "IT" }
}
```

> `zone` is omitted from the payload if not provided.

---

### `pop_get_sdi_document`

Retrieve an archived SdI (FatturaPA) document from POP storage by UUID.

**MCP inputs:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string (UUID) | ✅ | SdI document UUID |
| `response_format` | `"markdown"` \| `"json"` | — | Output format. Default: `"markdown"` |
| `environment` | string | — | Target environment |

**API payload sent:**

```json
{
  "license_key": "YOUR_LICENSE_KEY",
  "integration":