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

• 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

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

License

MIT