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

Tools

Documents

Payments

Nomenclatures

e-Factura

Webhooks

Company

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