Skip to main content
Glama

oblio-mcp-server

CI npm version node License: MIT

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 API

  • Full 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_cif

  • Client-side idempotency guard — pass an idempotencyKey to create_document and retries won't double-issue a document

  • Zod-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 the set_cif tool

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

OBLIO_API_EMAIL

yes

Oblio account email (Setari > Date Cont)

OBLIO_API_SECRET

yes

Oblio API secret (Setari > Date Cont)

OBLIO_CIF

no

Default company CIF; can be changed at runtime with set_cif

OBLIO_TOKEN_FILE

no

Path where the OAuth access token is persisted so it survives restarts (defaults to in-memory only)

OBLIO_BASE_URL

no

API origin, default https://www.oblio.eu. Point it at a mock or sandbox for tests and evals

Tools

Documents

Tool

Description

create_document

Issue an invoice, proforma or delivery notice (aviz); supports an optional idempotencyKey to guard against double-issue on retries

get_document

Fetch a single document by series name and number, with totals, status and a link

list_documents

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_document

Cancel (annul) a document; it stays in Oblio and can be restored later

restore_document

Restore a previously cancelled document to its active state

delete_document

Permanently delete a document (Oblio only allows deleting the last one in a series)

Payments

Tool

Description

collect_payment

Record a payment (incasare) against an existing invoice; defaults to the full remaining amount when no value is given

Nomenclatures

Tool

Description

get_nomenclatures

Fetch reference data: companies, saved clients, products, VAT rates, document series, languages, or management units (gestiuni)

e-Factura

Tool

Description

create_einvoice

Submit an issued invoice to Romania's SPV (e-Factura / ANAF)

get_einvoice

Fetch the SPV status and archive for a submitted invoice (0 = processing, 1 = success, 2 = errors, -1 = not sent)

Webhooks

Tool

Description

create_webhook

Subscribe an endpoint to an Oblio event: stock, <Doc>/SaveDraft, <Doc>/Update, <Doc>/Cancel (Doc = Invoice/Proforma/Notice/TaxReceipt) or Collect/Inserted. The endpoint must answer 200 and echo the base64 of the X-Oblio-Request-Id header

list_webhooks

List all webhook subscriptions with topic, endpoint and id

delete_webhook

Delete a webhook subscription by id

Company

Tool

Description

set_cif

Set the active company CIF used for subsequent requests (switch between companies on one account)

get_cif

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_document has a client-side idempotency guard, so agent retries don't silently issue duplicate invoices

  • Full 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 --noEmit

Keeping 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:

  1. Docs snapshot — scripts/oblio-docs-snapshot.mjs extracts the contract-bearing parts of the docs page (endpoints, parameter tables, response samples) into docs/oblio-api.snapshot.md. The oblio-docs-drift workflow re-fetches weekly and, on any change, opens a PR with the refreshed snapshot and the diff.

  2. Agent draft — when the ANTHROPIC_API_KEY repo secret is configured, the same workflow runs Claude Code on the drift PR branch to translate the docs diff into real src/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.

  3. 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 snapshot

License

MIT

Available Tools

12 tools
cancel_documentCancel documentA
DestructiveIdempotent

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

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

Return the company CIF currently used for Oblio requests.

Inputs: no named parameters.

get_documentGet documentA
Read-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 statusA
Read-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 nomenclaturesA
Read-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 documentsA
Read-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 documentA
Idempotent

Restore a previously cancelled document back to its active state.

Inputs: type (required), number (required), seriesName (required).

set_cifSet active company CIFA
Idempotent

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

    A4.2/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Unofficial 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.
      12
      47 npm
      5
      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
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -