oblio-mcp-server
A Model Context Protocol (MCP) server that lets an AI client (e.g. Claude Desktop) manage Oblio.eu invoicing through natural language.
Issue documents —
create_documentcreates invoices (factura), proformas, or delivery notices (avize), with client details, line items, currency, dates, optional inline payment, and anidempotencyKeyto prevent duplicate issuance on retries.Read documents —
get_documentfetches one document by series + number (totals, status, link);list_documentssearches with filters (client, series, number, issue-date range, draft/cancelled/collected flags, sorting, pagination, optional line items/payments/SPV status).Manage document lifecycle —
cancel_documentannuls a document (recoverable),restore_documentreactivates it,delete_documentpermanently removes it (only the last in a series).Record payments —
collect_paymentlogs an incasare against an invoice using any Oblio payment method (Chitanta, Ordin de plata, Card, CEC, etc.), defaulting to the full remaining amount.Submit to e-Factura / SPV —
create_einvoicesends an issued invoice's XML to ANAF;get_einvoicepolls its status (0 processing, 1 success, 2 errors, -1 not sent) and archive.Discover reference data —
get_nomenclatureslists companies, clients, products, VAT rates, series, languages, and management units (gestiuni) so valid values are known before issuing documents.Multi-company switching —
set_cifchanges the active company CIF at runtime;get_cifreports the current one.Note: the README also advertises webhook tools (
create_webhook,list_webhooks,delete_webhook), but they are absent from this server schema.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@oblio-mcp-server Issue invoice to client CIF RO12345678 for 1500 RON"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
oblio-mcp-server
A Model Context Protocol server for Oblio.eu — issue invoices, proformas and delivery notices, collect payments, submit e-Factura to Romania's SPV, and query your account's reference data through natural language, from Claude Desktop or any MCP client.
Unofficial community project. Not affiliated with or endorsed by Oblio Software; it builds on their public API and official Node SDK.
Features
Built on Oblio's official SDK (
@obliosoftware/oblioapi) — no hand-rolled HTTP layer for the core APIFull document lifecycle — create, fetch, list, cancel, restore and delete invoices, proformas and delivery notices (avize)
Payments — record collections (incasari) against invoices, with all Oblio payment methods
e-Factura / SPV — submit invoices to ANAF's SPV and poll their processing status
Nomenclatures — discover valid series names, VAT rates, saved clients, products, languages and management units before issuing documents
Webhooks — subscribe external endpoints to Oblio events (stock changes, document drafts/updates/cancellations, recorded payments)
Multi-company — switch the active company CIF at runtime via
set_cifClient-side idempotency guard — pass an
idempotencyKeytocreate_documentand retries won't double-issue a documentZod-validated inputs — every tool input is schema-checked with descriptive field docs
MCP tool annotations — read-only / destructive / idempotent hints on every tool, so clients can gate confirmations appropriately
Related MCP server: docnova-mcp
Prerequisites
Node.js >= 20
An Oblio.eu account with API access
Getting API credentials
In Oblio, go to Setari > Date Cont. You need:
the account email (acts as the OAuth client id)
the API secret (acts as the OAuth client secret)
your company CIF (e.g.
RO12345678) — optional at startup; it can also be set at runtime with theset_ciftool
Installation
Claude Desktop / MCP clients — via npx
Add to your MCP client configuration (e.g. claude_desktop_config.json). Straight from GitHub (npx builds it on first run):
{
"mcpServers": {
"oblio": {
"command": "npx",
"args": ["-y", "github:horatiuvlad/oblio-mcp-server"],
"env": {
"OBLIO_API_EMAIL": "you@example.com",
"OBLIO_API_SECRET": "your-api-secret",
"OBLIO_CIF": "RO12345678"
}
}
}
}Once the package is published to npm, "args": ["-y", "oblio-mcp-server"] will work as well.
From a local build
git clone https://github.com/horatiuvlad/oblio-mcp-server.git
cd oblio-mcp-server
npm install
npm run build{
"mcpServers": {
"oblio": {
"command": "node",
"args": ["/path/to/oblio-mcp-server/dist/index.js"],
"env": {
"OBLIO_API_EMAIL": "you@example.com",
"OBLIO_API_SECRET": "your-api-secret",
"OBLIO_CIF": "RO12345678"
}
}
}
}Environment variables
Variable | Required | Description |
| yes | Oblio account email (Setari > Date Cont) |
| yes | Oblio API secret (Setari > Date Cont) |
| no | Default company CIF; can be changed at runtime with |
| no | Path where the OAuth access token is persisted so it survives restarts (defaults to in-memory only) |
| no | API origin, default |
Tools
Documents
Tool | Description |
| Issue an invoice, proforma or delivery notice (aviz); supports an optional |
| Fetch a single document by series name and number, with totals, status and a link |
| List documents with filters: series, number, client (cif/email/phone/code), issue-date range, draft/cancelled/collected flags, optional line items / payments / SPV status, sorting and pagination |
| Cancel (annul) a document; it stays in Oblio and can be restored later |
| Restore a previously cancelled document to its active state |
| Permanently delete a document (Oblio only allows deleting the last one in a series) |
Payments
Tool | Description |
| Record a payment (incasare) against an existing invoice; defaults to the full remaining amount when no value is given |
Nomenclatures
Tool | Description |
| Fetch reference data: companies, saved clients, products, VAT rates, document series, languages, or management units (gestiuni) |
e-Factura
Tool | Description |
| Submit an issued invoice to Romania's SPV (e-Factura / ANAF) |
| Fetch the SPV status and archive for a submitted invoice (0 = processing, 1 = success, 2 = errors, -1 = not sent) |
Webhooks
Tool | Description |
| Subscribe an endpoint to an Oblio event: |
| List all webhook subscriptions with topic, endpoint and id |
| Delete a webhook subscription by id |
Company
Tool | Description |
| Set the active company CIF used for subsequent requests (switch between companies on one account) |
| Return the company CIF currently in effect |
Why another Oblio MCP?
It sits on Oblio's official SDK rather than reimplementing the API surface
It ships with a test suite and strict typechecking
create_documenthas a client-side idempotency guard, so agent retries don't silently issue duplicate invoicesFull e-Factura / SPV coverage — submit and track invoices with ANAF, not just issue them locally
Development
npm run build # compile to dist/
npm test # run the test suite
npm run typecheck # tsc --noEmitKeeping up with the Oblio API (docs drift)
Oblio publishes no machine-readable API spec — the HTML docs at
oblio.eu/api are the de-facto contract that
src/schemas.ts hand-encodes. Three layers guard against silent drift:
Docs snapshot —
scripts/oblio-docs-snapshot.mjsextracts the contract-bearing parts of the docs page (endpoints, parameter tables, response samples) intodocs/oblio-api.snapshot.md. Theoblio-docs-driftworkflow re-fetches weekly and, on any change, opens a PR with the refreshed snapshot and the diff.Agent draft — when the
ANTHROPIC_API_KEYrepo secret is configured, the same workflow runs Claude Code on the drift PR branch to translate the docs diff into realsrc/schemas.ts/ tool changes (including.describe()text), verified with typecheck + tests and pushed as a commit on the PR. A human still reviews and merges; without the secret the PR is opened with a manual checklist instead.SDK tripwire — Renovate flags releases of
@obliosoftware/oblioapi, which usually accompany API changes.
node scripts/oblio-docs-snapshot.mjs --check # exit 3 + diff on drift
node scripts/oblio-docs-snapshot.mjs --update # refresh the snapshotLicense
Available Tools
12 toolscancel_documentCancel documentADestructiveIdempotent
Cancel (annul) a document. The document stays in Oblio marked as cancelled and can later be restored with restore_document.
Inputs: type (required), number (required), seriesName (required).
collect_paymentCollect paymentA
Record a payment (incasare) against an existing invoice, identified by series name and number. The collect object specifies the payment method (Chitanta, Ordin de plata, Card, etc.) and optionally the amount and date; when no value is given the full remaining invoice amount is collected. Applies to invoices only.
Inputs: number (required), collect (required), seriesName (required).
create_documentCreate documentA
Issue a new fiscal document in Oblio: an invoice (factura), a proforma, or a delivery notice (aviz). Provide the document body (client, series, line items, dates). NOTE: Oblio has no draft state — the document is issued immediately. Pass an idempotencyKey to guard against accidental double-issue on retries.
Inputs: data (required), type (required), idempotencyKey.
create_einvoiceSubmit e-invoice to SPVA
Submit an existing Oblio invoice to Romania's SPV (e-Factura). The invoice must already be issued in Oblio; this sends its XML to ANAF. The response includes an einvoice status: 0 = processing, 1 = success, 2 = errors, -1 = not sent.
Inputs: number (required), seriesName (required).
delete_documentDelete documentADestructive
Permanently delete a document. Oblio only allows deleting the last document in a series; prefer cancel_document for anything else.
Inputs: type (required), number (required), seriesName (required).
get_cifGet active company CIFARead-onlyIdempotent
Return the company CIF currently used for Oblio requests.
Inputs: no named parameters.
get_documentGet documentARead-onlyIdempotent
Fetch a single document (invoice/proforma/notice) by its series name and number, including totals, status and a link.
Inputs: type (required), number (required), seriesName (required).
get_einvoiceGet e-invoice SPV statusARead-onlyIdempotent
Fetch the SPV (e-Factura) status and archive for an invoice previously submitted with create_einvoice. Status codes: 0 = processing, 1 = success, 2 = errors, -1 = not sent.
Inputs: number (required), seriesName (required).
get_nomenclaturesGet nomenclaturesARead-onlyIdempotent
Fetch Oblio reference data: companies on the account, saved clients, products, VAT rates, document series, languages, or management units (gestiuni). Use this to discover valid values (e.g. series names, VAT rate names) before creating documents. Supports an optional name filter and extra query filters such as pagination offset.
Inputs: type (required), name, filters.
list_documentsList documentsARead-onlyIdempotent
List documents of a given type, with optional filters: series, number, client, issue-date range, draft/cancelled flags, sorting and pagination.
Inputs: type (required), id, draft, client, +13 more.
restore_documentRestore documentAIdempotent
Restore a previously cancelled document back to its active state.
Inputs: type (required), number (required), seriesName (required).
set_cifSet active company CIFAIdempotent
Set the active company CIF used for all subsequent Oblio requests. Use this to switch between companies on the same Oblio account.
Inputs: cif (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a clearly distinct purpose: document lifecycle (create, get, list, cancel, restore, delete, collect payment), e-invoice (create, get status), company configuration (get/set CIF, get nomenclatures). No overlapping functionality that would confuse an agent.
All tool names follow a consistent verb_noun pattern in lowercase_snake_case (e.g., cancel_document, create_einvoice, list_documents). No mixing of conventions or confusing abbreviations.
With 12 tools, the server is well-scoped for a document management system. Each tool covers a necessary operation without redundancy or excess. The count is appropriate for the domain.
The tool set covers the core lifecycle of fiscal documents: create, read, list, cancel, restore, delete, and payment collection, plus e-invoice integration. A minor gap is the lack of an update tool, but this is typical for fiscal documents that cannot be modified after issuance. Overall sufficiently complete.
Maintenance
Related MCP Connectors
Invoicing you drive by talking to your AI: log time, raise invoices and track what's owed via MCP.
Connect Exact Online to your AI assistant via MCP. Manage Exact Online with natural language.
Create, send and track invoices from a conversation in Claude, ChatGPT or any MCP client that supports OAuth. Draft an invoice from one sentence or from last month's invoice for the same client, finalize it, email it to your client and send payment reminders for overdue ones. See revenue by month and by client, download PDFs and e-invoices (ZUGFeRD, XRechnung), and export DATEV packages for your tax advisor. Invoices follow the tax rules of 25 countries, including reverse charge and the small-business VAT exemption. New invoices are drafts, and nothing is emailed until you ask. Pay per invoice with no subscription: the first invoice is free.
Számlázz.hu MCP server for ChatGPT, Claude and any AI agent: issue invoice, cancel invoice, issue receipt, record payment and get invoice PDF in your own Számlázz.hu account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Számlázz.hu yourself; Cotlet does not store your password and you need no Számlázz.hu API key. About the official Számlázz.hu API: Yes. Számlázz.hu has an official API called Számla Agent, in operation since 2010, that issues, reverses and queries invoices and records payments over HTTP with XML (checked 14 Oct 2026). Setup and FAQ: https://cotlet.dev/integrations/szamlazz-hu-api-mcp-server
Related MCP Servers
- AlicenseAqualityBmaintenanceUnofficial MCP server for Oblio.eu accounting software enabling natural language interaction to create invoices, manage documents, collect payments, query nomenclatures, and submit e-Factura to Romania's SPV system.1247 npm5MIT

docnova-mcpofficial
AlicenseAqualityDmaintenanceMCP server for e-invoice platforms. Enables natural language querying of invoices, partners, company data, and financial reports.1810 npm6MIT- AlicenseAqualityBmaintenanceMCP server for the Elorus invoicing and accounting platform, enabling AI assistants to create invoices, manage contacts, and query financial data through natural language.434MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to search and inspect an invoice ledger, generate VAT summaries, run OCR on local documents, and use reusable prompts for chasing overdue invoices and reconciling entries.2-