oblio-mcp
This MCP server lets Claude and other MCP clients manage Oblio.eu accounting workflows through natural language: documents, payments, reference data, and Romanian e-Factura/SPV submissions.
Create invoices, proformas, and delivery notices with client/product details, optional inline payment, stock deduction, and e-Factura auto-submission.
Retrieve a single document by type, series, and number, including payment history.
List/filter documents with pagination by series, date range, client, draft/cancelled/collected status, and optional product/payment/e-Invoice details.
Delete the last document in a series, optionally removing its associated payment.
Cancel/annul and restore documents.
Record payments against invoices with methods like Chitanta, Ordin de plata, Card, CEC, etc.
Fetch nomenclatures/reference data: companies, clients, products, VAT rates, series, languages, and stock management locations.
Submit existing invoices to Romania's SPV e-Factura system and download e-Invoice archives.
Set and get the company CIF used for subsequent Oblio API requests.
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 create an invoice for client SC Test SRL 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.eu accounting MCP Server
MCP Server for the Oblio API, enabling Claude and other MCP-compatible platforms to interact with Oblio.eu accounting software.
Create invoices, manage documents, collect payments, query nomenclatures, and submit e-Factura to Romania's SPV system -- all through natural language.
This project is independent of Oblio. It uses their public API and the
@obliosoftware/oblioapipackage.
Prerequisites
Node.js >= 24 and npm >= 11.14. Node.js 24.18 and later already include a new enough npm (24.18 bundles npm 11.16). Node.js 24.17 and earlier bundle npm 11.13, which is too old.
An active Oblio.eu account with API access
Related MCP server: Cuéntica MCP
Setup
1. Get your Oblio API credentials
Log in at oblio.eu
Email and API secret: Setari > Date Cont (account settings)
Company CIF: Setari > Date firma (e.g.
RO37311090)
Oblio regenerates the API secret whenever the account password is reset.
2. Add the server in Claude Desktop
In Claude Desktop settings, add the marketplace https://github.com/valentinludu/oblio-mcp, then install the oblio-mcp plugin. Claude asks for your Oblio email, API secret, and company CIF. Node.js has to be installed, because the plugin starts the server with npx.
Claude Code can add the same marketplace from a shell:
claude plugin marketplace add valentinludu/oblio-mcp
claude plugin install oblio-mcp@oblioThe shell install does not ask for credentials. In a Claude Code session, run /plugin configure oblio-mcp@oblio and enter your Oblio email, API secret, and company CIF.
Other apps
Apps that take an MCP server config can use the same npm package. No clone or build is needed.
{
"mcpServers": {
"oblio": {
"command": "npx",
"args": ["-y", "oblio-mcp"],
"env": {
"OBLIO_API_EMAIL": "your-email@example.com",
"OBLIO_API_SECRET": "your-api-secret",
"CIF": "your-company-cif"
}
}
}
}Local clone
git clone https://github.com/valentinludu/oblio-mcp.git
cd oblio-mcp
npm installnpm install runs prepare, which builds dist/index.js.
{
"mcpServers": {
"oblio": {
"command": "node",
"args": ["/path/to/oblio-mcp/dist/index.js"],
"env": {
"OBLIO_API_EMAIL": "your-email@example.com",
"OBLIO_API_SECRET": "your-api-secret",
"CIF": "your-company-cif"
}
}
}
}Environment Variables
Required
Variable | Description |
| Your Oblio account email |
| API secret from Oblio settings |
| Company CIF from Setari > Date firma |
Tools
Document Management
Tool | Description |
| Creates an invoice (factura), proforma, or delivery notice (aviz). Requires client details, at least one product, a series name, and issue date. Returns the created document's series, number, and link. |
| Retrieves a single document by type, series name, and number. Returns document details, link, and payment history. |
| Lists and filters documents with pagination. Supports filtering by series, date range, client, draft/cancelled/collected status. Returns up to 100 results per page. |
| Permanently deletes a document. Only the last document in a series can be deleted. Optionally removes the associated payment, and accepts an idempotency key so the same delete is not processed twice. |
| Cancels (annuls) a document, marking it as void. The document remains in the system. |
| Restores a previously cancelled document, making it active again. |
Payments
Tool | Description |
| Records a payment against an existing invoice. Supports payment types: Chitanta, Bon fiscal, Ordin de plata, Card, CEC, and others. Defaults to the full invoice amount if value is omitted. |
Nomenclatures (Reference Data)
Tool | Description |
| Fetches reference data from Oblio. Types: |
e-Factura (SPV)
Tool | Description |
| Submits an existing invoice to Romania's SPV system for e-Factura. Returns status code: 0=processing, 1=success, 2=errors, -1=not sent. |
| Downloads the e-Invoice archive from SPV for a previously submitted invoice. Returns the file as a base64 resource, or JSON when the API responds with JSON. |
Configuration
Tool | Description |
| Sets the company CIF (tax ID) used for all subsequent API requests. |
| Returns the currently configured company CIF. |
Prompts
The server includes 28 prompt templates for common operations: creating documents, retrieving documents, cancelling/restoring/deleting documents, searching nomenclatures, collecting payments, listing invoices, and managing e-Factura submissions.
Troubleshooting
If you encounter issues:
Verify your Oblio account is active and has API access
Check that
OBLIO_API_EMAILandOBLIO_API_SECRETare correctly setIf authentication fails after a password reset, copy the new API secret from Setari > Date Cont
Ensure your company CIF is set (via the
CIFenv var or theset_ciftool)Confirm you have the necessary permissions for the operations you're performing
Releasing
Run
npm version 1.0.1 --no-git-tag-versionto updatepackage.jsonandpackage-lock.json.Set the same version in
.claude-plugin/plugin.json.Commit and push.
Run
npm loginif you are not already logged in, thennpm stage publish --access publicornpm publish --access public. Both runprepare, which buildsdist/before packing.
License
Available Tools
12 toolscancel_documentCancel DocumentAIdempotent
Cancels (annuls) a document in Oblio via PUT /api/docs/{type}/cancel. The document is marked as void but remains in the system. Returns: documentType, seriesName, number, and link to the cancelled document.
Inputs: type (required), seriesName (required), number (required).
collect_paymentCollect PaymentA
Records a payment (incasare) against an existing invoice via PUT /api/docs/invoice/collect. Identifies the invoice by seriesName + number. The collect object specifies payment method (type), document number, optional value (defaults to full invoice total), and optional issueDate. Available payment types: Chitanta, Bon fiscal, Bon fiscal card, Alta incasare numerar, Ordin de plata, Mandat postal, Card, CEC, Bilet ordin, Alta incasare banca, Ramburs. Returns: documentType, seriesName, number, link, and collects array with all payments on the invoice.
Inputs: seriesName (required), number (required), collect (required).
create_documentCreate DocumentA
Creates an invoice (factura), proforma, or delivery notice (aviz) in Oblio via POST /api/docs/{type}. Required fields: cif, client (with at least name), seriesName, issueDate, and at least one product. Optional: inline payment via collect, reference to existing proforma/notice via referenceDocument, stock deduction via useStock, auto e-Factura submission via spvExtern, and idempotencyKey to prevent duplicates. Returns: seriesName, number, and a link to view/download the created document.
Inputs: type (required), data (required).
create_einvoiceSend e-Invoice to SPVA
Submits an existing invoice to Romania's SPV system via POST /api/docs/einvoice. The invoice must already exist in Oblio. Returns: text (explanation), sent (boolean), code (-1=not sent, 2=errors, 0=processing, 1=success).
Inputs: seriesName (required), number (required).
delete_documentDelete DocumentADestructive
Permanently deletes a document from Oblio via DELETE /api/docs/{type}. Constraint: only the last document in a series can be deleted. This cannot be undone. Set deleteCollect to true to also remove the associated payment (invoices only). Returns: documentType, seriesName, number of the deleted document.
Inputs: type (required), seriesName (required), number (required), deleteCollect, +1 more.
get_cifGet Company CIFARead-onlyIdempotent
Returns the currently configured company CIF (tax ID) used for Oblio API requests.
Inputs: no named parameters.
get_documentGet DocumentARead-onlyIdempotent
Retrieves a single document from Oblio via GET /api/docs/{type}. Returns: documentType, seriesName, number, link (view/download URL), and collects array (list of payments with issueDate, type, number, value).
Inputs: type (required), seriesName (required), number (required).
get_einvoice_archiveGet e-Invoice Archive from SPVARead-onlyIdempotent
Downloads the e-Invoice archive (XML) from Romania's SPV system via GET /api/docs/einvoice. The invoice must have been previously submitted to SPV. Returns the SPV archive data for the specified invoice.
Inputs: seriesName (required), number (required).
get_nomenclaturesGet NomenclaturesARead-onlyIdempotent
Fetches reference/lookup data from Oblio via GET /api/nomenclature/{type}. Types and their returns:
"companies": returns cif, company name, userTypeAccess for each account company
"clients": returns cif, name, rc, code, address, state, city, iban, bank, email, phone, vatPayer. Filterable by name, clientCif
"products": returns name, code, description, measuringUnit, productType, price, currency, vatName, vatPercentage, vatIncluded, and stock[] for stocked items. Filterable by name, code, management, workStation
"vat_rates": returns name, percent, default for each VAT rate
"series": returns type (Factura/Proforma/Aviz), name, start, next, default for each document series
"languages": returns code and name for each configured language
"management": returns management, workStation, managementType for each stock location Paginated: max 250 results per page, use offset filter (0, 250, 500...) for next pages.
Inputs: type (required), name, filters.
list_documentsList DocumentsARead-onlyIdempotent
Lists documents from Oblio via GET /api/docs/{type}/list with filters and pagination. Each result contains: id, draft, canceled, seriesName, number, issueDate, dueDate, precision, currency, exchangeRate, total, collected (0=unpaid, 1=paid), mentions, useStock, type, link, einvoiceStatus (text, sent, code), and client object (clientId, cif, name, rc, code, address, etc.). Optionally include product lines (withProducts=1), payment details (withCollects=1), or e-Invoice SPV status (withEinvoiceStatus=1). Max 100 results per page.
Inputs: type (required), filters (required).
restore_documentRestore DocumentAIdempotent
Restores a previously cancelled document in Oblio via PUT /api/docs/{type}/restore. Reverses a cancellation and makes the document active again. Returns: documentType, seriesName, number, and link to the restored document.
Inputs: type (required), seriesName (required), number (required).
set_cifSet Company CIFAIdempotent
Sets the company CIF (Cod de Identificare Fiscala / tax ID) used for all subsequent Oblio API requests. Must be called before other tools if the CIF environment variable is not configured. The CIF identifies which company's data to access (e.g. RO37311090).
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 targets a distinct operation (cancel vs delete, create document vs create e-invoice, etc.). Even similar-sounding tools like cancel_document and delete_document are clearly differentiated by descriptions, leaving no ambiguity for an agent.
All tools follow a consistent verb_noun pattern in snake_case (e.g., cancel_document, collect_payment, get_nomenclatures). There are no mixed conventions or vague verbs, ensuring predictable naming.
With 12 tools, the server is well-scoped for managing documents in Oblio. Each tool serves a clear purpose without redundancy, covering configuration, document lifecycle, payments, and e-invoice handling.
The tool surface covers creation, retrieval, listing, cancellation, restoration, deletion, payment collection, and e-invoice submission. However, there is no update/edit tool for documents (e.g., modifying invoice lines), which is a notable gap but manageable via cancel+recreate.
Maintenance
Related MCP Connectors
Official Timbrix MCP server: stamp, cancel, and query Mexican CFDI 4.0 invoices from AI agents.
MCP server for ABRA Flexi — accounting, contacts, stock and draft-checked invoice creation.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- AlicenseAqualityDmaintenanceUnofficial MCP server for Siigo Colombian electronic invoicing software that enables AI to manage customers, products, invoices, credit notes, and journals through the Siigo API with configurable safety modes.191MIT
- AlicenseBqualityDmaintenanceMCP server to interact with the Cuéntica accounting API, allowing users to manage invoices, expenses, income, clients, providers, and bank accounts via natural language.592MIT

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