Finland Invoices (Peppol BIS 3.0 via Storecove)

Official3 toolsLive

by junter1989k-ai · JavaScript

Finland Peppol/Finvoice e-invoices for AI agents: send, check recipient, get delivery proof.

Topics

ai-agentclaudee-invoicefinlandinvoicemcpmcp-serverpeppolstorecovevatwishpool

Captured live from the server via tools/list.

create_invoice

Send a Finland B2B/B2G electronic invoice (verkkolasku) over the Peppol network in Peppol BIS 3.0 / EN 16931 format via Storecove (a certified Peppol Access Point). Finland mandates structured e-invoicing for public-sector suppliers (B2G) since 2020-04-01, and a business has the right to require an e-invoice from another business (turnover over EUR 10,000) under the Act on Electronic Invoicing (241/2019) — not a blanket B2B mandate, but Peppol/Finvoice is the Finnish rail. Builds the structured invoice JSON from seller + buyer (name, Finnish VAT FIxxxxxxxx and/or Y-tunnus business ID, address) and line items (description, quantity, net unit price, VAT rate 25.5/14/10/0), computes the Finnish VAT (ALV) breakdown, and submits it under YOUR OWN Storecove credentials. Bring your own credential as header x-storecove-key. You must also pass seller_legal_entity_id — the legalEntityId of the sender you created in your Storecove account. Finnish VAT rates: 25.5 (standard, decimal, since 2024-09-01), 14 (food/restaurant), 10 (books/pharmaceuticals/passenger transport), 0 (zero-rated/exempt/reverse charge). Amounts in EUR. Delivery over Peppol is asynchronous: this returns a submission guid — use get_delivery_evidence with it to fetch the delivery proof/status. Tip: call check_recipient first to confirm the buyer is reachable on Peppol. There is no cancel over Peppol: to reverse an invoice you issue a credit note (a new invoice).

Parameters24

seller_legal_entity_id	string	required	REQUIRED. The Storecove legalEntityId of the sender (created in your Storecove account under Senders). Numeric id, passed through to Storecove.
seller_name	string	required	Seller legal/company name.
seller_vat	string	optional	Seller Finnish VAT number, format FIxxxxxxxx (FI + 8 digits, derived from the Y-tunnus). Provide this and/or seller_business_id.
seller_business_id	string	optional	Optional seller Finnish business ID (Y-tunnus), 7+1 digits, format NNNNNNN-N.
seller_address	string	required	Seller street address.
seller_city	string	required	Seller city.
seller_zip	string	required	Seller postal code.
seller_country	string	optional	Seller country code. Default FI.
customer_name	string	required	Buyer legal/company name.
customer_vat	string	optional	Buyer Finnish VAT number FIxxxxxxxx. Provide this and/or customer_business_id (used to route on Peppol if no explicit recipient id is given).
customer_business_id	string	optional	Optional buyer Finnish business ID (Y-tunnus), 7+1 digits.
customer_address	string	required	Buyer street address.
customer_city	string	required	Buyer city.
customer_zip	string	required	Buyer postal code.
customer_country	string	optional	Buyer country code. Default FI.
recipient_peppol_scheme	string	optional	Optional explicit Peppol routing scheme (EAS/ISO6523). Finland: 0037 (OVT / Y-tunnus) or 0213 (VAT). Default 0037 when routing by business ID.
recipient_peppol_id	string	optional	Optional explicit Peppol participant identifier to route to (overrides deriving from the customer VAT/business ID).
recipient_email	string	optional	Optional email fallback — used if the recipient is not on Peppol (Storecove can email a copy).
invoice_number	string	optional	Invoice number. Auto-generated if omitted.
issue_date	string	optional	Invoice issue date, YYYY-MM-DD. Default: today (UTC).
due_date	string	optional	Optional payment due date, YYYY-MM-DD.
currency	string	optional	Document currency. Default EUR.
note	string	optional	Optional free-text note on the invoice.
lines	array	required	Invoice line items. Each: description, unit_price (net, VAT-exclusive, EUR), vat_rate (25.5\|14\|10\|0), optional quantity (default 1), optional tax_category (S standard / Z zero-rated / E exempt / AE reverse charge; default S for rate>0, Z for rate 0), optional item_name.

Raw schema

{
  "type": "object",
  "properties": {
    "seller_legal_entity_id": {
      "type": "string",
      "description": "REQUIRED. The Storecove legalEntityId of the sender (created in your Storecove account under Senders). Numeric id, passed through to Storecove."
    },
    "seller_name": {
      "type": "string",
      "description": "Seller legal/company name."
    },
    "seller_vat": {
      "type": "string",
      "description": "Seller Finnish VAT number, format FIxxxxxxxx (FI + 8 digits, derived from the Y-tunnus). Provide this and/or seller_business_id."
    },
    "seller_business_id": {
      "type": "string",
      "description": "Optional seller Finnish business ID (Y-tunnus), 7+1 digits, format NNNNNNN-N."
    },
    "seller_address": {
      "type": "string",
      "description": "Seller street address."
    },
    "seller_city": {
      "type": "string",
      "description": "Seller city."
    },
    "seller_zip": {
      "type": "string",
      "description": "Seller postal code."
    },
    "seller_country": {
      "type": "string",
      "description": "Seller country code. Default FI."
    },
    "customer_name": {
      "type": "string",
      "description": "Buyer legal/company name."
    },
    "customer_vat": {
      "type": "string",
      "description": "Buyer Finnish VAT number FIxxxxxxxx. Provide this and/or customer_business_id (used to route on Peppol if no explicit recipient id is given)."
    },
    "customer_business_id": {
      "type": "string",
      "description": "Optional buyer Finnish business ID (Y-tunnus), 7+1 digits."
    },
    "customer_address": {
      "type": "string",
      "description": "Buyer street address."
    },
    "customer_city": {
      "type": "string",
      "description": "Buyer city."
    },
    "customer_zip": {
      "type": "string",
      "description": "Buyer postal code."
    },
    "customer_country": {
      "type": "string",
      "description": "Buyer country code. Default FI."
    },
    "recipient_peppol_scheme": {
      "type": "string",
      "description": "Optional explicit Peppol routing scheme (EAS/ISO6523). Finland: 0037 (OVT / Y-tunnus) or 0213 (VAT). Default 0037 when routing by business ID."
    },
    "recipient_peppol_id": {
      "type": "string",
      "description": "Optional explicit Peppol participant identifier to route to (overrides deriving from the customer VAT/business ID)."
    },
    "recipient_email": {
      "type": "string",
      "description": "Optional email fallback — used if the recipient is not on Peppol (Storecove can email a copy)."
    },
    "invoice_number": {
      "type": "string",
      "description": "Invoice number. Auto-generated if omitted."
    },
    "issue_date": {
      "type": "string",
      "description": "Invoice issue date, YYYY-MM-DD. Default: today (UTC)."
    },
    "due_date": {
      "type": "string",
      "description": "Optional payment due date, YYYY-MM-DD."
    },
    "currency": {
      "type": "string",
      "description": "Document currency. Default EUR."
    },
    "note": {
      "type": "string",
      "description": "Optional free-text note on the invoice."
    },
    "lines": {
      "type": "array",
      "minItems": 1,
      "description": "Invoice line items. Each: description, unit_price (net, VAT-exclusive, EUR), vat_rate (25.5|14|10|0), optional quantity (default 1), optional tax_category (S standard / Z zero-rated / E exempt / AE reverse charge; default S for rate>0, Z for rate 0), optional item_name.",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Line description."
          },
          "unit_price": {
            "type": "number",
            "description": "Net unit price in EUR, VAT-exclusive."
          },
          "vat_rate": {
            "type": "number",
            "description": "Finnish VAT rate percent: 25.5 (standard, decimal), 14, 10 (reduced), or 0."
          },
          "quantity": {
            "type": "number",
            "description": "Quantity. Default 1."
          },
          "tax_category": {
            "type": "string",
            "description": "Optional EN 16931 tax category: S / Z / E / AE. Default derived from vat_rate."
          },
          "item_name": {
            "type": "string",
            "description": "Optional item name (defaults to description)."
          }
        },
        "required": [
          "description",
          "unit_price",
          "vat_rate"
        ]
      }
    }
  },
  "required": [
    "seller_legal_entity_id",
    "seller_name",
    "seller_address",
    "seller_city",
    "seller_zip",
    "customer_name",
    "customer_address",
    "customer_city",
    "customer_zip",
    "lines"
  ]
}

check_recipient

Check whether a business can receive electronic invoices on the Peppol network before you send (Storecove POST /discovery/receives). This is the safe pre-flight for Finnish B2B/B2G: pass the recipient identifier and scheme and learn if they are a registered Peppol participant. For Finland use scheme 0037 with the Y-tunnus business ID (OVT), or 0213 with the VAT number FIxxxxxxxx. Returns can_receive=true when the party is reachable (Storecove code OK). If can_receive is false, the recipient is not on Peppol — fall back to recipient_email in create_invoice or ask them to register.

Parameters4

identifier	string	required	The recipient Peppol identifier. Finland: the Y-tunnus business ID (scheme 0037, OVT) or the VAT number FIxxxxxxxx (scheme 0213).
scheme	string	optional	Peppol/ISO6523 scheme. Default 0037 (Finnish OVT / Y-tunnus). Use 0213 for a Finnish VAT number.
network	string	optional	Network to check. Default peppol.
document_types	array	optional	Document types to check receipt for. Default ["invoice"].

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "description": "The recipient Peppol identifier. Finland: the Y-tunnus business ID (scheme 0037, OVT) or the VAT number FIxxxxxxxx (scheme 0213)."
    },
    "scheme": {
      "type": "string",
      "description": "Peppol/ISO6523 scheme. Default 0037 (Finnish OVT / Y-tunnus). Use 0213 for a Finnish VAT number."
    },
    "network": {
      "type": "string",
      "description": "Network to check. Default peppol."
    },
    "document_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Document types to check receipt for. Default [\"invoice\"]."
    }
  },
  "required": [
    "identifier"
  ]
}

get_delivery_evidence

Fetch the delivery evidence for an invoice sent by create_invoice, using its submission guid (Storecove GET /document_submissions/{guid}/evidence). Peppol delivery is asynchronous — this returns the proof of what was sent and the delivery status/receipt from the recipient Access Point. Call it shortly after create_invoice and poll until it reports delivery. Safe to call anytime.

Parameters1

guid

string

required

The submission guid returned by create_invoice.

Raw schema

{
  "type": "object",
  "properties": {
    "guid": {
      "type": "string",
      "description": "The submission guid returned by create_invoice."
    }
  },
  "required": [
    "guid"
  ]
}

README.md7 KBView on GitHub

Finland Invoice MCP 🇫🇮 — How can my AI agent send a Peppol e-invoice (verkkolasku) in Finland?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "finland-invoice": {
      "type": "http",
      "url": "https://inv-fi.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/finland-invoice-mcp && cd finland-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent send Finland B2B/B2G electronic invoices (verkkolasku) over the Peppol network in Peppol BIS 3.0 / EN 16931 format via Storecove, a certified Peppol Access Point. It builds the structured invoice, computes the Finnish VAT (ALV) breakdown — including the 25.5% decimal standard rate — and delivers it under the merchant's own Storecove account. Stateless, bring-your-own credentials, never stores anything.

Live endpoint: https://inv-fi.wishpool.app/mcp · Registry: app.wishpool/finland-invoice-mcp

Why now — the Finnish mandate

Finland mandates structured e-invoicing (verkkolasku) for public-sector suppliers (B2G) since 2020-04-01. For B2B, a business has the right to require an e-invoice from another business (when turnover exceeds EUR 10,000) under the Act on Electronic Invoicing (241/2019) — a right to demand, not a blanket obligation to send. Peppol/Finvoice is the Finnish rail, so sending over Peppol now is future-proof.

The 25.5% decimal VAT rate

Finland's standard VAT (ALV) rate is 25.5% — a decimal rate, in force since 2024-09-01. This server's VAT math handles fractional rates. Valid rates: 25.5 (standard), 14 (food/restaurant), 10 (books/pharmaceuticals/passenger transport), 0 (zero-rated/exempt/reverse charge).

Quick start

json

{
  "mcpServers": {
    "finland-invoice": {
      "type": "http",
      "url": "https://inv-fi.wishpool.app/mcp",
      "headers": {
        "x-storecove-key": "your-storecove-api-key"
      }
    }
  }
}

Sign up at storecove.com — the merchant is the Peppol Access Point account holder. Request a free 30-day sandbox account from Storecove for a test key (sandbox does not need production onboarding). Create your sender under Senders to get the legalEntityId you pass as seller_legal_entity_id. Sandbox vs production is determined by the account your key belongs to — the base URL is the same. Authentication is HTTP Bearer with your key. Your key stays with you and travels per-request; this server never stores it.

Tools

Tool	What it does
`check_recipient`	Peppol participant discovery — is the buyer reachable on Peppol before you send? Pass the identifier (Y-tunnus scheme `0037`, or VAT scheme `0213`). Returns `can_receive`. The safe pre-flight.
`create_invoice`	Build a Peppol BIS 3.0 invoice from seller + buyer (Finnish VAT `FIxxxxxxxx` / Y-tunnus business ID, address) and line items (description, net unit price, VAT rate 25.5/14/10/0, quantity), then submit over Peppol via Storecove. Returns a submission `guid` + computed VAT totals (`taxable`, `vat`, `total`).
`get_delivery_evidence`	Fetch the proof of what was sent and the Peppol delivery status by `guid`.

Amounts are in EUR. Finnish VAT (ALV) rates: 25.5 (standard, decimal), 14 (food/restaurant), 10 (books/pharmaceuticals/passenger transport), 0 (zero-rated/exempt/reverse charge). Parties identified by Finnish VAT (FIxxxxxxxx) and/or Y-tunnus business ID (7+1 digits).

No cancel over Peppol — to reverse an invoice you issue a credit note (a new invoice). create_invoice needs seller_legal_entity_id (your Storecove sender id). Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them.

VAT math (deterministic)

Per line amountExcludingVat = round2(quantity × unit_price); grouped by (rate, category) into taxSubtotals (taxableAmount, taxAmount = round2(taxable × rate / 100)); gross amountIncludingVat = taxable + tax. Examples (note the decimal 25.5% rate):

100 + 50 both @25.5% → taxable 150.00 / vat 38.25 / total 188.25
200 @25.5% + 100 @14% → taxable 300.00 / vat 65.00 (51 + 14) / total 365.00
2×50 @25.5% + 3×10 @10% + 1×25 @0% → taxable 155.00 / vat 28.50 (25.50 + 3.00 + 0) / total 183.50
rounding at the decimal rate: 33.33 @25.5% → vat 8.50 (from 8.49915) / total 41.83

Endpoints wrapped (Storecove REST)

Base: https://api.storecove.com/api/v2 (single base URL; auth = HTTP Bearer with your API key)
Send: POST /document_submissions — JSON { legalEntityId, routing, document:{ documentType:"invoice", invoice:{…} } } → { guid }
Evidence: GET /document_submissions/{guid}/evidence — proof of what was sent + Peppol delivery status
Discovery: POST /discovery/receives — JSON { documentTypes, network, metaScheme, scheme, identifier } → { code:"OK", email }
Verified probe (2026-07-10): a fake Bearer key really hits api.storecove.com/api/v2 → 403 {"errors":[{"source":"generic","details":"Not Authorized"}]} (endpoint alive; BYO = the merchant's own key validates).

Develop

bash

node test/serve.js   # local server on :3238
node test/e2e.js     # VAT math (incl. 25.5% decimal) + Peppol JSON structure + protocol + validation + policy + fake-key live probe

Safety

Pure stateless translation layer over the Storecove REST API. Storecove is the certified Peppol Access Point under the merchant's own account; this service never signs, never onboards, and never stores anything. The API key travels per-request in a header, and funds are never touched — this issues tax invoices, it does not move money. Privacy policy.

Sister servers

Local invoices, one family: Belgium Peppol (inv-be) · Sweden Peppol (inv-se) · Italy FatturaPA (inv-it) · Malaysia MyInvois (inv-my) · Mexico CFDI (inv-mx) · Brazil NF-e (inv-br) · India GST (inv-in). Storecove also covers Norway, Denmark, the Netherlands and Luxembourg on Peppol — those sister countries replicate this exact server. Local logistics: logi.wishpool.app. Local payments in 81 countries: mcp.wishpool.app.

MIT licensed.

Install

Tools (3)

create_invoicecheck_recipientget_delivery_evidence

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-fi.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "finland-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-fi.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.