Skip to main content
Glama

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/oblioapi package.

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@oblio

The 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 install

npm 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

OBLIO_API_EMAIL

Your Oblio account email

OBLIO_API_SECRET

API secret from Oblio settings

CIF

Company CIF from Setari > Date firma

Tools

Document Management

Tool

Description

create_document

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.

get_document

Retrieves a single document by type, series name, and number. Returns document details, link, and payment history.

list_documents

Lists and filters documents with pagination. Supports filtering by series, date range, client, draft/cancelled/collected status. Returns up to 100 results per page.

delete_document

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.

cancel_document

Cancels (annuls) a document, marking it as void. The document remains in the system.

restore_document

Restores a previously cancelled document, making it active again.

Payments

Tool

Description

collect_payment

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

get_nomenclatures

Fetches reference data from Oblio. Types: companies, clients, products, vat_rates, series, languages, management. Results are paginated (max 250 per page).

e-Factura (SPV)

Tool

Description

create_einvoice

Submits an existing invoice to Romania's SPV system for e-Factura. Returns status code: 0=processing, 1=success, 2=errors, -1=not sent.

get_einvoice_archive

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

set_cif

Sets the company CIF (tax ID) used for all subsequent API requests.

get_cif

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:

  1. Verify your Oblio account is active and has API access

  2. Check that OBLIO_API_EMAIL and OBLIO_API_SECRET are correctly set

  3. If authentication fails after a password reset, copy the new API secret from Setari > Date Cont

  4. Ensure your company CIF is set (via the CIF env var or the set_cif tool)

  5. Confirm you have the necessary permissions for the operations you're performing

Releasing

  1. Run npm version 1.0.1 --no-git-tag-version to update package.json and package-lock.json.

  2. Set the same version in .claude-plugin/plugin.json.

  3. Commit and push.

  4. Run npm login if you are not already logged in, then npm stage publish --access public or npm publish --access public. Both run prepare, which builds dist/ before packing.

License

MIT

Available Tools

12 tools
cancel_documentCancel DocumentA
Idempotent

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 DocumentA
Destructive

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 CIFA
Read-onlyIdempotent

Returns the currently configured company CIF (tax ID) used for Oblio API requests.

Inputs: no named parameters.

get_documentGet DocumentA
Read-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 SPVA
Read-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 NomenclaturesA
Read-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 DocumentsA
Read-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 DocumentA
Idempotent

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 CIFA
Idempotent

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

    A4.3/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Unofficial 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.
      19
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server to interact with the Cuéntica accounting API, allowing users to manage invoices, expenses, income, clients, providers, and bank accounts via natural language.
      59
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for e-invoice platforms. Enables natural language querying of invoices, partners, company data, and financial reports.
      18
      10 npm
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the Elorus invoicing and accounting platform, enabling AI assistants to create invoices, manage contacts, and query financial data through natural language.
      43
      4
      MIT