Clearvo MCP Server
The Clearvo MCP server lets Claude Code, Cursor, Windsurf, and any MCP-compatible AI tool submit invoices to tax authorities, calculate tax, validate business tax numbers, and manage entities — without writing a line of integration code.
- “Submit an invoice for €5,000 to Acme SpA in Italy”
- “Calculate tax for a B2B sale from Germany to France”
- “Validate this UK VAT number: GB123456789”
- “Create a new entity for our Irish subsidiary”
Quick setup
Create a free account at app.clearvo.io.
Your API key is issued immediately — no sales call, no waiting.
Use a csk_test_... sandbox key for development.
Select your editor below — the server runs via npx, no global install needed:
Run this command once in your terminal. The --scope user flag registers the server globally across all projects.
claude mcp add --scope user clearvo -e CLEARVO_API_KEY=csk_live_... -e CLEARVO_ENTITY_ID=your_entity_id -- npx -y @clearvo/mcp
Find your entity ID in Settings → Business Profile, or run list_entities after setup. Then restart Claude Code — the clearvo server will appear in /mcp.
Add to ~/.cursor/mcp.json for global use, or .cursor/mcp.json inside a project.
{
"mcpServers": {
"clearvo": {
"command": "npx",
"args": ["-y", "@clearvo/mcp"],
"env": {
"CLEARVO_API_KEY": "csk_live_..."
}
}
}
}
Add to Windsurf's global MCP settings file at ~/.codeium/windsurf/mcp_settings.json.
{
"mcpServers": {
"clearvo": {
"command": "npx",
"args": ["-y", "@clearvo/mcp"],
"env": {
"CLEARVO_API_KEY": "csk_live_..."
}
}
}
}
VS Code 1.99+ with Copilot Agent: create .vscode/mcp.json in your project. For Cline or Continue extensions, use mcpServers format instead of servers.
{
"servers": {
"clearvo": {
"command": "npx",
"args": ["-y", "@clearvo/mcp"],
"env": {
"CLEARVO_API_KEY": "csk_live_..."
}
}
}
}
Restart Claude Code, then paste this into a chat:
Use clearvo to get the e-invoicing requirements for Italy, then submit a
test invoice for €1,000 from Clearvo Test Ltd (IE1234567T) to Acme SpA
(IT12345678901, Milan) for "Software licence Q3 2026"
Claude will call get_requirements, then submit_invoice, and return a referenceId you can poll for its status.
Working across several business profiles
When you connect an AI tool by signing in (instead of an API key), you choose what the connection may act on. If you belong to two or more business profiles, the consent screen offers All my business profiles as well as a single one.
- Access follows your account live. A business profile you are added to later appears without reconnecting, and access you lose is removed straight away.
- Your role in each business profile still applies. Where you are a viewer or auditor, the connection stays read-only for that profile.
- Account administrators choose one business profile per connection.
- A connection made for one business profile behaves exactly as before: you never need to pass
entityId.
Every tool except reference-data and account-level ones (for example list_tax_categories, validate_tax_number, create_entity) takes an optional entityId. list_entities returns only the business profiles the connection may act on. If a connection covers several business profiles and a call has no entityId, the tool does not guess: it replies asking you to choose one and call list_entities. A business profile outside the connection's access is refused.
List my business profiles with clearvo, then calculate tax for a 500 EUR
sale to a German consumer in the Irish business profile.
Claude calls list_entities, picks the matching business profile, and passes its id as entityId to calculate_tax.
Available tools
The MCP server exposes more than 100 tools — every public API operation is available — and Claude selects the right one automatically based on what you ask. The table below lists the most commonly used ones; ask Claude "what Clearvo tools can you use?" for the full list.
| Tool | What it does |
|---|---|
| Invoicing | |
submit_invoice |
Submit a B2B invoice to Italy SDI, Poland KSeF, Romania ANAF, or any of 20+ supported authorities |
poll_status |
Check invoice status — RECEIVED, PENDING, WAITING_FOR_YOU, WAITING_FOR_PLATFORM, ACCUMULATED, COMPLETED, REJECTED, CANCELLED, SKIPPED, or NOT_APPLICABLE, with stage, reason, issues and customerResponse |
list_invoices |
List and filter invoices by country, status, reason, buyer response or document family, with cursor pagination. Received (inbound) invoices carry their intake channel, validation summary and attachments |
get_invoice |
Fetch full detail for one invoice — event log, authority references, rejection reason, submitted XML |
list_invoice_attachments |
List the supporting files sent with, or received on, an invoice, with a download URL for each stored file. Read-only; the files themselves download through the SDK, CLI or API |
get_requirements |
Get country requirements: mandate dates, VAT number format, Peppol scheme, authority portal URL |
list_country_coverage |
List the countries and mandates covered, with status (live, beta, coming soon, not supported, no mandate) and go-live date where confirmed |
| Tax calculation | |
calculate_tax |
Calculate tax (VAT, GST, or sales tax) for a transaction in 100+ countries |
list_tax_calculations |
List committed tax calculations — jurisdiction, amounts, tax totals, customer type |
get_tax_settings |
Read account-level tax calculation settings — VAT validation mode, default tax category, US address precision |
update_tax_settings |
Update account-level tax calculation settings |
validate_tax_number |
Validate a VAT number against EU VIES, HMRC, Brreg, ABN, or 100+ other authorities. Optional companyName adds a name match against the registered name |
validate_tax_numbers_batch |
Validate up to 20 tax numbers in a single request |
query_tax_number_check_history |
Find the stored authority check that applied to tax numbers on a given date, with its proof reference |
| Tax registrations | |
list_registrations |
List an entity's tax registrations and obligations — VAT by country, OSS/IOSS schemes, compliance threshold status |
add_registration |
Record a new tax registration — VAT, IOSS, OSS, or any other scheme |
set_registration_collection |
Set the date a registration starts collecting tax — required before it applies to any calculation |
| Entities & team | |
list_entities |
List the business profiles this connection can act on (all of them for an account-scoped key or an "All my business profiles" connection). Use the returned id as entityId on other tools |
create_entity |
Create a new legal entity and receive an entity-scoped API key |
update_entity |
Update an entity's name or business profile address, or confirm it has no tax registrations yet |
invite_team_member |
Invite a teammate to your Clearvo account by email |
get_setup_status |
Check what's left to finish setting up the account — mirrors the dashboard's "Getting Started" checklist |
| Authority credentials | |
set_pl_credentials |
Register Poland KSeF credentials (NIP + API token) — a token needs "dostęp do faktur" (access) permission to receive invoices, not just "wysyłka faktur" (send) |
set_hu_credentials |
Register Hungary NAV Online Számla technical user credentials |
set_ar_credentials |
Register Argentina AFIP WSFE certificate credentials |
| Product catalogue | |
list_products |
List the product catalogue — products store pre-classified tax categories to skip re-classification on every invoice |
create_product |
Create a product with a name, SKU, and tax category slug |
update_product |
Update a product — most commonly to set or correct its tax category after a calculate_tax call |
| Webhooks | |
list_webhooks |
List registered webhook endpoints |
create_webhook |
Register a new webhook to receive real-time invoice status events |
delete_webhook |
Deactivate a webhook endpoint |
| Exemption certificates | |
create_exemption_certificate |
Record a customer's tax exemption certificate so it auto-applies during calculate_tax |
upload_exemption_document |
Attach the signed certificate PDF to an exemption certificate |
Example: submit an invoice to Italy
Here is what happens when you ask Claude to submit an Italian invoice end-to-end.
1. Claude calls get_requirements
{
"country": "IT",
"countryName": "Italy",
"eInvoicingMandatory": true,
"mandatoryFrom": "2019-01-01",
"authority": "Agenzia delle Entrate (SDI)",
"vatNumberFormat": "IT followed by 11 digits",
"vatNumberRegex": "^IT[0-9]{11}$",
"peppolScheme": "0211",
"supportedDocumentTypes": [
{ "code": "380", "name": "Invoice" },
{ "code": "381", "name": "Credit note" }
]
}
2. Claude calls submit_invoice
{
"referenceId": "IT-2026-001",
"status": "PENDING",
"message": "Invoice submitted to SDI. Use poll_status to track clearance."
}
3. Claude calls poll_status until accepted
{
"referenceId": "IT-2026-001",
"status": "COMPLETED",
"stage": "cleared",
"reason": "ACCEPTED",
"statusLabel": "Cleared by SDI",
"updatedAt": "2026-06-24T14:32:01Z"
}
referenceId immediately — Claude can poll on your behalf.
TypeScript SDK
For programmatic use in Node.js or browser TypeScript projects.
npm install @clearvo/sdk
import { ClearvoClient } from '@clearvo/sdk';
const client = new ClearvoClient({ apiKey: process.env.CLEARVO_API_KEY! });
const result = await client.calculateTax({
currency: 'EUR',
supplier: { billingAddress: { country: 'DE' } },
customer: {
taxId: 'FR12345678901', // a verified tax ID is what makes this B2B
// b2bOverride: true, // use instead when you know the buyer is a business but have no tax ID
billingAddress: { country: 'FR' },
},
lineItems: [{ id: '1', amount: 10000, productName: 'SaaS subscription' }],
});
console.log(result.taxCode); // 'K' — intra-EU reverse charge
console.log(result.summary.totalTax); // 0
console.log(result.lineItems[0].rate); // 0
const entity = await client.createEntity({
legalName: 'Acme GmbH',
country: 'DE',
vatNumber: 'DE123456789',
});
// entity.apiKey — save this immediately, shown once only
console.log(entity.entityId);
console.log(entity.apiKey); // csk_live_...
const result = await client.validateTaxNumber('GB', 'GB123456789');
// { valid: true, status: 'VALID', name: 'Acme Ltd', country: 'GB' }
CLI
Zero-install CLI via npx. Useful for CI pipelines and quick testing.
# Set your API key once
export CLEARVO_API_KEY=csk_live_...
# List entities
npx @clearvo/cli entities list --pretty
# Get country requirements
npx @clearvo/cli requirements --country IT --pretty
# List country coverage (no API key needed)
npx @clearvo/cli coverage --pretty
# Validate a tax number
npx @clearvo/cli validate-tin --country DE --number DE123456789
# Submit an invoice from a JSON file
npx @clearvo/cli send invoice.json --pretty
# Poll invoice status
npx @clearvo/cli status ref-abc123 --country IT --pretty
# Calculate tax from a JSON file
npx @clearvo/cli calculate transaction.json --pretty
Or install globally: npm install -g @clearvo/cli
Authentication
| Key prefix | Environment | Use for |
|---|---|---|
csk_live_... |
Production | Real authority submissions |
csk_test_... |
Sandbox | Development and testing — no real authority calls |
Most tools — submit_invoice, calculate_tax, tax registrations, and more — accept
either key type: entity-scoped keys resolve automatically, account-scoped keys and connections covering several business profiles need an
entityId specified per call (see working across several business profiles). create_entity is the one exception —
it requires an account-scoped key, since it creates a new entity under the account.
Get a key at app.clearvo.io/settings.
create_entity is shown once only — it is never stored in plaintext.
Save it immediately to a secrets manager (AWS Secrets Manager, Azure Key Vault, etc.).
Ready to submit your first invoice?
Production API key issued in seconds. No sales call.
Get your free API key