Oblio

Oblio MCP server

Issue and track a Romanian company's invoices from your AI assistant, through Oblio's API. It reads clients, products, series, VAT rates and issued invoices; it issues invoices and proformas, records payments, and cancels, restores, reverses or deletes invoices. Every tool that makes, changes or unmakes a fiscal document is money: your client asks you first, and shows the total computed the way ANAF checks it.

You need an Oblio account, its API secret, and the tax id (CIF) of the company the server should act on. There is no sandbox: an invoice issued here is real and takes the next number in its series.

What you can ask

• "Which invoices from September are still unpaid?"
• "Invoice Client SRL for 8 hours of consulting at 1,000 RON an hour plus 21% VAT, due in 30 days."
• "Client SRL paid 1,000 EUR on invoice FCT 0042 by bank transfer today. Record it."
• "Turn proforma PRF 0007 into an invoice."
• "Reverse invoice FCT 0042, and keep the payment recorded on it."

Install

With Claude Code:

claude mcp add oblio -e OBLIO_CONFIG="<path to Oblio app.json>" -- npx -y @foreverworks/mcp-oblio

Claude Desktop (Settings, Developer, Edit Config) and most other clients read the same command as JSON:

{

"mcpServers": { "oblio": { "command": "npx", "args": ["-y", "@foreverworks/mcp-oblio"], "env": { "OBLIO_CONFIG": " " } } } }

Each runs the published package on Node 22.19 or newer. VS Code and the Claude Desktop bundle ask for OBLIO_CONFIG as they add the server. Cursor reads it from your environment instead (${env:OBLIO_CONFIG}), so set it before you start Cursor. Configuration says what it holds.

From a clone

git clone https://github.com/foreverworks/mcps.git && cd mcps

npm ci && npm run build claude mcp add oblio -e OBLIO_CONFIG=" " -- node "$PWD/servers/oblio/dist/index.js"

In a JSON configuration, the command is node and its one argument the full path of servers/oblio/dist/index.js. To share one running copy between several clients over HTTP, see docs/deploying.md.

Configuration

app.json holds three values, all required:

{

"client_id": " ", "client_secret": " ", "company_cif": " " }

company_cif has no default, so no call can act on a company nobody named. api_base and token_url override Oblio's endpoints, for tests or a proxy. The server never writes app.json, and its errors name a bad field, never a value.

Getting the API secret

1. Sign in to the Oblio web app.
2. Open Settings, then Account Data (Setari, Date cont), and copy the API secret.
3. Put it in app.json as client_secret, with the email you signed in with as client_id.

Oblio makes a new secret every time the account's password is reset, so after a reset app.json needs the new one.

The state folder holds access_token.json, the hour-long token Oblio issues for the secret, written with mode 0600 and locked across processes. The variables every server shares (transport, limits, confirmation) are in docs/configuration.md.

First run

1. Ask your assistant to run Oblio's health check. It answers with the account, the company CIF from app.json, and whether the account reaches that company. A refused secret shows up here, before anything is issued.
2. Ask for your series (list_series) and VAT rates (list_vat_rates): an invoice names its series and each line's rate by the names Oblio gives them.

From a shell, node dist/index.js --health prints one OBLIO: line and exits non-zero when the credentials do not work, which suits a timer.

Tools

read changes nothing; write changes something in your Oblio account; money makes, changes or unmakes a fiscal document, and your client asks you before each call.

Money

The seven money tools are marked so in tools/list, and your client asks you to approve each call (Claude Code does, in every permission mode). With MCP_CONFIRM=elicit the server asks you itself instead, in one line computed from the arguments. For example:

Issue invoice in series FCT to Client SRL (CIF RO87654329): 9680.00 RON incl. VAT 1680.00 (1 line), dated 2026-09-28, due 2026-10-28, marked paid by Ordin de plata OP 7001

Record 1000.00 EUR paid on invoice FCT 0042 to Client SRL, Ordin de plata OP 7001, 2026-10-02, leaving 210.00 EUR unpaid Issue a reversing invoice for FCT 0042, Client SRL, total -9680.00 RON, in series FCT, keeping the payment recorded on it DELETE invoice FCT 0042 totalling 9680.00 permanently (no undo; only the last number in a series can be deleted, and anything already sent to ANAF stays there)

The first line is the document in Document input, below. The last is delete_invoice given expect_total; without it the line says "total not given, so not checked". The server puts its name first, so you read oblio: Issue invoice ....

What you approve is what is issued:

• The total you confirm is the total issued. It is computed by documentTotal (the kit's invoiceTotals.ts), the same function whose result create_invoice returns as computedTotal. After issuing, the document is read back, and if Oblio's total differs the call fails with reason: "total_mismatch", naming the document that was issued. invoice_from_proforma reads the proforma first and holds the invoice to its total.
• Cancel, restore and delete read the invoice first and answer with what it totalled, the document Oblio acted on and the company's CIF. Given expect_total, a number that names an invoice of another total changes nothing. (Oblio's document read carries no buyer, so the buyer cannot be checked the same way.)
• A payment is checked against the invoice: the server refuses a cancelled invoice, one already paid in full, and an amount over what is still owed, saying how much that is.

Troubleshooting

`auth`: "Oblio refused the client_id and secret". The secret changed, usually after a password reset. Copy the new one from Settings, Account Data into app.json.

`api` with `reason: "outcome_unknown"` after an issue or a delete. The connection dropped, so nobody knows whether Oblio acted. Look the document up first (get_invoice, or Oblio's web app). If it is not there, call again with the idempotency_key the error reported: Oblio will not issue the same key twice. A repeated collect_invoice is safe as it is: it finds the payment if it landed and records nothing.

`api` with `reason: "total_mismatch"`. The document was issued, but Oblio's total is not the one you confirmed. Open it (get_invoice or get_proforma) and cancel it if it is wrong; do not issue it again.

`api` with Oblio's own message, such as "Seria FCT nu exista". The message names the field or series at fault; list_series and list_vat_rates give the names Oblio expects.

`api` with status 401 or 403 on a call. The account cannot act on the company in company_cif; health and list_companies show which companies it reaches.

`api` with `reason: "drift"`. Oblio's answer changed shape. The server refuses to guess; please report it.

How it works

Document input

create_invoice and create_proforma take the document as a validated input modelled on Oblio's "Parametri document" table, in snake_case. The company's CIF is not part of it: it comes from app.json, so no pasted example can issue against another company.

{

"client": { "name": "Client SRL", "cif": "RO87654329", "vat_payer": true }, "series_name": "FCT", "issue_date": "2026-09-28", "due_date": "2026-10-28", "currency": "RON", "products": [ { "name": "Consulting", "price": "1000.00", "quantity": "8", "measuring_unit": "ora", "vat_name": "Normala", "vat_percentage": "21", "vat_included": false, "product_type": "Serviciu" } ], "collect": { "type": "Ordin de plata", "document_number": "OP 7001" } }

• Every amount is a decimal string ("1000.00"), checked by a pattern and sent to Oblio as that string, so it never passes through a floating-point number. The arithmetic is the kit's exact decimal.ts.
• **`vat_