# io.github.popapidev/pop-mcp (npm · @getpopapi/pop-mcp)

Italian e-invoicing (FatturaPA/SdI), Peppol, PDF invoice generation, and account onboarding via POP

- Trust score: 64/100 (medium)
- Change this week: +23
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@getpopapi/pop-mcp`: 64/100 (this document), [markdown](https://verifymcp.io/servers/popapidev-pop-mcp/getpopapi-pop-mcp.md), [page](https://verifymcp.io/servers/popapidev-pop-mcp/getpopapi-pop-mcp)

## Channel facts

- Registry: `npm`
- Package: `@getpopapi/pop-mcp`
- Version: `1.1.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (108 of 109), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (108 of 109), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 13 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 55/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 3241 tokens (~249/item across 13 items; 13 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 94/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 82% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add popapidev-pop-mcp -- npx -y @getpopapi/pop-mcp
```

### Codex

```bash
codex mcp add popapidev-pop-mcp -- npx -y @getpopapi/pop-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "popapidev-pop-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@getpopapi/pop-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add popapidev-pop-mcp --command npx --arg -y --arg @getpopapi/pop-mcp
```

### Hermes

```yaml
mcp_servers:
  popapidev-pop-mcp:
    command: "npx"
    args: ["-y", "@getpopapi/pop-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "popapidev-pop-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@getpopapi/pop-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 64, +42)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Security disclosure: fail → unverified
- [functional regression] Capabilities: pass → unverified
- [functional improvement] Schema quality: unverified → good
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] License: unverified → pass
- [functional improvement] Stability: unverified → 0.20
- [functional] Licence: MIT

### 2026-08-01 (score 22, +5)

- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] MCP protocol: unverified → pass

### 2026-07-31 (score 17, −6)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 23, −1)

- [security regression] Malware scan: pass → unverified
- [functional improvement] Tool coverage: unverified → 100

### 2026-07-28 (score 24, −17)

- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 41)

First indexed and scored.

## MCP tools (13)

### `pop_create_sdi_invoice` (~440 tokens)

Create SdI / FatturaPA Invoice (XML)

Generate an Italian FatturaPA electronic invoice in XML format and optionally submit it to the SdI (Sistema di Interscambio).

This tool creates a compliant FatturaPA XML document that satisfies Italian e-invoicing regulations (D.Lgs. 127/2015). The invoice can be generated locally (XML only) or submitted directly to SdI for B2B/B2C delivery.

Key facts:
\- Supports invoice types: TD01 (invoice) and TD04 (credit note)
\- Customer types: private, company, freelance, pa (Public Administration)
\- For Private customers: sdi_type must be '0000000' and tax_id_code (codice fiscale) is required
\- For PA customers: use version='FPA12' and the 6-char PA office code as sdi_type
\- VAT rates: 22%, 10%, 5%, 4%, 0% (with nature code required when 0%)
\- Submission to SdI requires Growth+ plan with active SdI via POP integration

Returns: XML document string when not submitting, or JSON with UUID when submitting.

Args:
  \- data: Complete invoice data (transmitter, supplier, customer, line items, payment)
  \- submit_to_sdi: Set true to automatically submit to SdI (requires active integration)
  \- integration: Override integration config (sdi-via-pop, pop-to-webhook, fatture-in-cloud)

Input parameters:

- `data` (object, required): Full invoice data object
- `environment` (string): Target environment (e.g. 'sandbox')
- `integration`: Integration configuration — use this to override the default behaviour or deliver via webhook/Fatture in Cloud. Overrides submit_to_sdi if set.
- `plugin_version` (string): Caller application version
- `site_title` (string): Site/shop title
- `site_url` (string): Site/shop URL
- `submit_to_sdi` (boolean): If true, automatically submits the invoice to the Italian SdI (Sistema di Interscambio). Requires active SdI via POP integration (Growth+ plan).

### `pop_create_peppol_invoice` (~296 tokens)

Create Peppol / UBL Invoice

Generate a Peppol e-invoice in UBL 2.1 format and optionally submit it to the Peppol network.

Peppol (Pan-European Public Procurement Online) enables cross-border B2B electronic invoicing across Europe. The API generates a compliant UBL 2.1 XML document.

Restrictions:
\- Customer type must be 'company' or 'freelance' (Peppol does not support private individuals)
\- Submission requires active Peppol via POP integration (Basic+ plan)
\- The customer must have a valid Peppol participant ID

Returns: UBL XML string or JSON with UUID when submitting to the network.

Args:
  \- data: Complete invoice data (customer_type must be 'company' or 'freelance')
  \- submit_to_peppol: Set true to submit to Peppol network
  \- integration: Override integration config

Input parameters:

- `data` (object, required): Full invoice data object. Note: Peppol only supports company and freelance customer types.
- `environment` (string): Target environment (e.g. 'sandbox')
- `integration`: Integration configuration override
- `plugin_version` (string)
- `site_title` (string)
- `site_url` (string)
- `submit_to_peppol` (boolean): If true, automatically submits to the Peppol network. Requires active Peppol via POP integration.

### `pop_create_pdf_invoice` (~316 tokens)

Create PDF Invoice

Generate a PDF invoice with optional branding and email delivery.

Creates a printable PDF invoice. Can include company logo, custom footer, and billing/shipping addresses. The PDF can be emailed automatically to up to 3 recipients (Basic+ plan required for email).

Configuration via data.pdf:
  \- invoice_html: '"true"' to generate HTML version
  \- doc_type_title: Title shown on document (e.g. 'Invoice', 'Receipt', 'Credit Note')
  \- logo_url: Company logo URL (HTTPS)
  \- head.store_info_address: Supplier address displayed in header
  \- head.billing: Customer billing address array
  \- email_invoice.to: Array of up to 3 recipient emails (requires Basic+ plan)
  \- email_invoice.from: Reply-to email address
  \- footer_text: Custom footer message

Returns: PDF binary data or confirmation JSON with email delivery status.

Args:
  \- data: Invoice data with data.pdf configuration populated
  \- send_email: Set true to deliver PDF via email (requires email_invoice in data.pdf)

Input parameters:

- `data` (object, required): Full invoice data object. Must include data.pdf configuration for PDF-specific settings.
- `environment` (string): Target environment (e.g. 'sandbox')
- `plugin_version` (string)
- `send_email` (boolean): If true, emails the PDF to recipients in data.pdf.email_invoice.to (max 3 addresses, Basic+ plan required).
- `site_title` (string)
- `site_url` (string)

### `pop_get_invoice_status` (~233 tokens)

Get SdI Invoice Status

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

After submitting an invoice to the Italian SdI (Sistema di Interscambio), the system processes it asynchronously and sends notifications. This tool polls the current status and all notifications.

SdI notification statuses:
  \- pending: Invoice received, awaiting processing
  \- accepted: Invoice accepted and delivered to recipient
  \- rejected: Invoice rejected (check details for reason and correction steps)
  \- delivery: Delivery notification received

Note: SdI processing can take from minutes to hours. If no notifications are returned, wait and retry.

Args:
  \- uuid: The UUID returned by pop_create_sdi_invoice (when submit_to_sdi=true)
  \- response_format: 'markdown' for readable output, 'json' for structured data

Input parameters:

- `environment` (string): Target environment (e.g. 'sandbox')
- `response_format` (string): Output format: 'markdown' for human-readable, 'json' for structured data
- `uuid` (string, required): Invoice UUID returned by pop_create_sdi_invoice when submit_to_sdi=true

### `pop_get_peppol_document` (~190 tokens)

Get Peppol Document

Retrieve a Peppol document from the network by UUID.

After a Peppol invoice is submitted, use this tool to retrieve the processed document or check its delivery status on the Peppol network.

Args:
  \- uuid: The Peppol document UUID from pop_create_peppol_invoice
  \- zone: Country code for the Peppol access point (e.g. 'BE' for Belgium). Required for some regions.
  \- response_format: Output format

Input parameters:

- `environment` (string): Target environment (e.g. 'sandbox')
- `response_format` (string)
- `uuid` (string, required): Peppol document UUID returned by pop_create_peppol_invoice when submit_to_peppol=true
- `zone` (string): Country code of the Peppol access point zone (e.g. 'BE' for Belgium). Required for some countries.

### `pop_get_sdi_document` (~132 tokens)

Get SdI Document

Retrieve an SdI document from POP storage by UUID.

Fetches a previously submitted or preserved SdI (FatturaPA) document. Useful for auditing, re-downloading, or verifying stored invoices.

Requires: Growth+ plan with active SdI via POP integration.

Args:
  \- uuid: The SdI document UUID
  \- response_format: 'markdown' for readable summary, 'json' for raw data

Input parameters:

- `environment` (string): Target environment (e.g. 'sandbox')
- `response_format` (string)
- `uuid` (string, required): SdI document UUID to retrieve

### `pop_verify_sdi_document` (~175 tokens)

Verify SdI Document

Validate an SdI (FatturaPA) XML document for compliance before submission.

Use this tool to check if an SdI XML document passes XML syntax validation and Italian e-invoicing compliance checks — without actually submitting it. This helps catch errors before they result in SdI rejections.

Common validation checks:
  \- XML schema conformance
  \- Fiscal code format
  \- VAT number validity
  \- Required field presence
  \- Amount consistency

Requires: Growth+ plan with active SdI via POP integration and registered business.

Args:
  \- xml_base64: The SdI XML document encoded as a Base64 string

Input parameters:

- `environment` (string): Target environment (e.g. 'sandbox')
- `xml_base64` (string, required): The SdI XML document encoded as a Base64 string

### `pop_preserve_document` (~185 tokens)

Preserve / Archive SdI Document

Archive an SdI document in long-term digital storage (conservazione sostitutiva).

Italian law requires electronic invoices to be preserved for 10 years. This tool archives a document in POP's certified digital storage system to meet legal preservation requirements.

IMPORTANT: Only call this tool when pop_get_invoice_status returns a status of RC (Ricevuta di Consegna — successfully delivered) or MC (Mancata Consegna — delivery failed but SdI accepted). Do NOT call for other statuses such as NS, EC, SE, or DT.

Requires: Growth+ plan with active SdI via POP integration.

Args:
  \- uuid: UUID of the SdI document to archive

Input parameters:

- `environment` (string): Target environment (e.g. 'sandbox')
- `uuid` (string, required): UUID of the SdI document to archive/preserve in long-term storage

### `pop_onboarding_request_otp` (~213 tokens)

Request Onboarding OTP

Start the POP onboarding flow by sending a one-time password (OTP) to an email address.

This is step 1 of 5 in the onboarding sequence:
  request-otp → verify-otp → get_status → get_account_setup → save_account_setup

Key behaviours:
\- The OTP code is returned directly in the response (not just by email). Read otp_code from the response.
\- OTP expires in 10 minutes. Pass it to pop_onboarding_verify_otp immediately.
\- If the email does not exist, a new POP account is created automatically.
\- For administrator accounts, no OTP is issued. Use the admin password as the otp field in verify-otp instead.

No API key required for this call.

Input parameters:

- `email` (string, required): Email address to send the OTP to. If the account does not exist it will be created automatically.
- `lang` (string): Locale hint (e.g. 'en', 'it'). Stored in the session context but does not affect response language.

### `pop_onboarding_verify_otp` (~268 tokens)

Verify Onboarding OTP

Verify the OTP from pop_onboarding_request_otp and obtain an onboarding token.

This is step 2 of 5 in the onboarding sequence.

Key behaviours:
\- Returns an onboarding_token (48-character string). Save it — required for all subsequent steps.
\- Token expires 30 minutes after issue. No refresh endpoint; restart from request-otp if expired.
\- token_issued_at and token_expires_at are ISO 8601 strings (e.g. 2026-05-26T13:47:15+00:00).
\- wizard_variant is 'basic' if no country is saved yet — it updates after save_account_setup sets the country.
\- If wizard_required is false after this step, the account is already fully set up. No further steps needed.
\- For administrator accounts: pass the admin password as the otp field.

No API key required for this call.

Input parameters:

- `email` (string, required): Must match the email used in pop_onboarding_request_otp
- `otp` (string, required): 6-digit OTP from the request-otp response (or the administrator password for admin accounts)
- `platform` (string): Client identifier recorded in the session. Default: 'mcp'
- `site_id` (string): Optional caller site domain or identifier

### `pop_onboarding_get_status` (~176 tokens)

Get Onboarding Status

Retrieve the current onboarding state for the authenticated account.

This is step 3 of 5 in the onboarding sequence (optional — use to poll state or check progress).

Returns: state, next_action, wizard_variant, wizard_completed, required_fields, step_visibility, integration_state.

Does NOT return configurations (field values). Use pop_onboarding_get_account_setup for those.

Key behaviours:
\- auth_source will be 'onboarding_token' confirming the token was accepted.
\- step_visibility.integration = false means SdI/Peppol toggles do not apply to this account (basic variant).
\- integration_state.ksef.status = 'not_supported_in_onboarding_yet' is correct — not an error.

Input parameters:

- `onboarding_token` (string, required): Token returned by pop_onboarding_verify_otp. Expires 30 minutes after issue.

### `pop_onboarding_get_account_setup` (~244 tokens)

Get Account Setup Configuration

Retrieve the full account setup payload: current field values, lookup tables, capabilities, and integration state.

This is step 4 of 5 in the onboarding sequence. Call this before save_account_setup to understand:
\- Which fields are already saved (non-null in configurations)
\- Which fields are locked (field_locks = true) and cannot be changed
\- Which integrations are available for the account country (capabilities)
\- Valid tax regime codes (lookup.tax_regimes keyed by country)
\- Valid Peppol scheme options (lookup.peppol.endpoint_scheme_options)
\- Which integration toggles can be set (allowed_integration_toggles)

Key behaviours:
\- Null values in configurations = field not yet saved, must be provided in save_account_setup.
\- Locked fields (🔒) must not be changed — the API will reject modifications.
\- Use capabilities.supports_sdi_onboarding and supports_peppol_onboarding to decide which integration to offer.
\- lookup.countries labels are in Italian regardless of the lang field.

Input parameters:

- `onboarding_token` (string, required): Token returned by pop_onboarding_verify_otp. Expires 30 minutes after issue.

### `pop_onboarding_save_account_setup` (~373 tokens)

Save Account Setup Configuration

Save the account setup configuration and optionally activate SdI or Peppol integration.

This is step 5 of 5 in the onboarding sequence.

Integration rules:
\- To activate SdI (Italy/San Marino): set active_sdipop_integration=1 and active_peppol_integration=0
\- To activate Peppol (EU countries): set active_peppol_integration=1 and active_sdipop_integration=0, and provide all peppol_* fields
\- SdI and Peppol are mutually exclusive — never set both to 1
\- For 'basic' variant accounts (non-IT, non-EU): do not send integration toggle fields

Key behaviours:
\- general_store_vat_number must be unique on the target environment. 422 if already in use.
\- Sending 0 for an integration toggle means "do not activate" — the value stores as null in configurations.
  Always read the effective activation state from integration_state.environments.*.sdi.enabled.
\- Once wizard is complete (wizard_completed=true), calling this again returns the current state without writing (applied_changes=false).
\- Once Peppol is registered (peppol_legal_entity_uuid set), all Peppol fields are locked permanently.
\- If SdI activation fails at ACube, the account data is still saved — retry is safe.

Input parameters:

- `configurations` (object, required): Account setup fields. Send only the fields you want to set. Locked fields (field_locks=true) cannot be changed.
- `environment` (string): Which POP environment to configure. 'live' affects your production account; 'sandbox' is for testing.
- `onboarding_token` (string, required): Token returned by pop_onboarding_verify_otp. Expires 30 minutes after issue.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/popapidev-pop-mcp/getpopapi-pop-mcp#diagnostics

## Score history

- 2026-08-03: 64
- 2026-08-02: 64
- 2026-08-01: 22
- 2026-07-31: 17
- 2026-07-30: 23
- 2026-07-28: 24
- 2026-07-27: 41

## Links

- npm package: https://www.npmjs.com/package/@getpopapi/pop-mcp
- Socket report: https://socket.dev/npm/package/@getpopapi/pop-mcp
- Repository: https://github.com/getpopapi/pop-mcp
- Changelog RSS feed: https://verifymcp.io/servers/popapidev-pop-mcp/getpopapi-pop-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/popapidev-pop-mcp/getpopapi-pop-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/popapidev-pop-mcp/getpopapi-pop-mcp