smartbill-mcp

An MCP server for the SmartBill Cloud API. It lets an MCP client issue and manage Romanian invoices, proformas and payments, download document PDFs, and read VAT rates, series and stock levels.

Run in hosted mode with a database, it also adds session-backed reporting tools the public API cannot provide — customer roster, receivables/aging, client statements and ledgers, collections and product sales (see Portal report tools).

Hosted instance: a public deployment runs at https://smartbill-mcp-coolify.bogdanripa.com/. Open it in a browser to connect your own SmartBill account and generate a connector URL.

It runs two ways:

• stdio, single account, on your machine — credentials come from the environment.

• HTTP, multi-tenant, hosted — credentials arrive with each request, so one deployment serves any number of SmartBill accounts.

Credentials

You need a SmartBill Cloud account. How credentials reach the server depends on the mode:

• stdio uses an API token, generated in Contul meu → Integrari → API, set in the environment (below). A SmartBill token has full account access and no scoping — anything holding it can issue and delete real fiscal documents.

• HTTP asks the user for their SmartBill email and password during the OAuth sign-in and reads the token itself; nothing needs to be generated by hand. See Authentication.

Related MCP server: oblio-mcp

Running over stdio

npm install
npm run build
cp .env.example .env   # then fill it in

The series defaults are optional but convenient: with them set, tools can be called with just a document number. Without them, pass seriesName explicitly.

claude mcp add smartbill \
  --env SMARTBILL_USERNAME=you@example.com \
  --env SMARTBILL_TOKEN=your-api-token \
  --env SMARTBILL_VAT_CODE=RO12345678 \
  --env SMARTBILL_INVOICE_SERIES=FF \
  -- node /absolute/path/to/smartbill-mcp/dist/index.js

The token is read once at startup, turned into an Authorization: Basic header inside the HTTP client, and never enters the model's context — no tool takes a credential argument, so it cannot surface in a tool result.

Running over HTTP (multi-tenant)

npm run build
npm run start:http     # or: node dist/index.js --http

HTTP mode is OAuth-authenticated and needs a database, so DATABASE_URL and SMARTBILL_SESSION_KEY are required. Without them the server still starts, but refuses MCP requests with 503 — it has no way to authenticate a caller. No per-account SMARTBILL_* secrets are read in this mode; each account signs in through the OAuth flow.

GET /health answers without credentials, for platform health checks:

{ "status": "ok", "version": "0.1.0", "commit": "9f2c1ab..." }

commit is the git SHA the image was built from, baked in via the BUILD_SHA build argument ("dev" outside a built image). It exists because a redeploy leaves the outgoing container serving: a check that only asks for a 200 is answered by the container being replaced. The deploy workflow waits for commit to equal the SHA it just built, so it tests the new container rather than racing it.

Authentication (OAuth 2.1)

The connector URL carries nothing secret — it is just the MCP endpoint:

https://smartbill.example.com/mcp

A client adds that URL, discovers the server requires authorization, and runs the standard OAuth 2.1 authorization-code + PKCE flow. The server is both the authorization server and the resource server, and exposes:

On the /authorize page the user signs in with their SmartBill email and password. The server logs into SmartBill, scrapes the account's API token and CIF, stores the tenant (password + session cookies encrypted at rest with SMARTBILL_SESSION_KEY), and issues an authorization code bound to it. The client exchanges that for an access token and calls the MCP endpoint with:

Authorization: Bearer <access token>

The SmartBill token never leaves the server. The client only ever holds an opaque, revocable access token that maps to the stored tenant — so a leaked token is revoked here (POST /revoke, or by deleting the row) without touching the SmartBill credential. Access tokens and authorization codes are stored hashed (SHA-256); codes are single-use; PKCE (S256) is required.

An unauthenticated MCP request gets 401 with a WWW-Authenticate header pointing at the resource metadata — that is what kicks off the flow.

The homepage

The marketing / overview page (what the connector does and how to add it) is a static site under web/, served by the platform's CDN — the backend renders no HTML. It is not a setup form; sign-in happens on the server-rendered /authorize page during the OAuth flow. Direct hits to the backend container at / (before the frontend is published, or from a health check) get a small JSON status blob instead. The connector URL on the page is derived client-side from location.origin, so the same file works on any host.

Deploying

The Dockerfile builds for the runtime Prionman expects — linux/arm64, listening on port 80, no secrets baked into the image:

docker build --platform linux/arm64 -t smartbill-mcp .
docker run -p 8080:80 smartbill-mcp

The static homepage in web/ is deployed separately from the container: the CI workflow zips it and uploads it to the platform's static host, which serves it at / in front of the backend. Paths the bundle doesn't contain — /mcp, /authorize, /token, /.well-known/*, /health — fall through to the container.

Tools

Invoices

Estimates (proforme)

Payments

Account and catalogue

Portal report tools

Registered only in hosted mode with DATABASE_URL + SMARTBILL_SESSION_KEY set. They read the SmartBill web account through an authenticated session to answer the questions the public API cannot — the customer roster and the reports behind SmartBill Cloud's dashboards. All read-only.

Signing in (via the OAuth flow) stores the account login encrypted with SMARTBILL_SESSION_KEY, so an expired session is renewed automatically. After three consecutive sign-in failures the account is frozen and the tools ask the user to authorize again, which clears the block.

How the tools are documented

The descriptions are written for a model choosing between them, not just for a human reading the list. Every tool states what it does, when to reach for it, what it returns, and which sibling tool to use instead when it is the wrong choice — delete_invoice points at cancel_invoice, create_invoice points at create_invoice_from_estimate, and so on. Irreversible tools say so and ask for confirmation; read-only ones are marked readOnlyHint and destructive ones destructiveHint, so clients can gate them.

The server also ships instructions, which explain the domain a model has to get right up front: how series and numbers work, the difference between an invoice, a proforma and a payment, and the asymmetry between deleting, cancelling and reversing.

test/documentation.test.ts enforces this — it fails the build if a tool loses its title, gets a thin description, stops saying when to use it, drops one of the cross-references, or grows an undocumented parameter.

Behaviour worth knowing

Errors. SmartBill reports business failures with HTTP 200 and a non-empty errorText (and the email endpoint uses a status.code instead). Both are turned into tool errors, so a failed call never looks like a success.

Rate limiting. SmartBill allows 3 calls per second. The client serialises requests and spaces them out, so a burst of tool calls queues instead of failing.

PDFs. Delivery is chosen with as. The default is text over HTTP (the extracted text layer — the only readable form of a document's fields) and file over stdio (writes to SMARTBILL_DOWNLOAD_DIR). To hand the actual file to the user, pass as: "document": the PDF comes back as an MCP embedded resource the client can display or save. as: "base64" returns the raw bytes for a programmatic caller.

Email fields. SmartBill expects the email subject and body base64-encoded. Pass plain text; the encoding is handled for you.

Irreversibility. Only the last document in a series can be deleted. Older documents can be cancelled (cancel_invoice) or reversed with a storno invoice (create_reverse_invoice). The server tells the model this in its instructions and marks the destructive tools accordingly, but the client still decides whether to prompt — treat write tools as needing confirmation.

Development

npm test          # vitest, no network access needed
npm run typecheck
npm run dev       # stdio, from source

Tests drive the real MCP server — over an in-memory transport for the tool layer and over a real socket for the HTTP layer — with a stubbed fetch, so they cover the tool schemas, the request bodies sent to SmartBill, the error mapping and per-tenant credential isolation.

Notes on the API surface

SmartBill's reference lives at https://api.smartbill.ro/, which serves a Swagger spec at https://api.smartbill.ro/data/swagger.json. Every endpoint, field name and query parameter used here has been checked against it. Three details are worth flagging:

• delete_payment calls DELETE /payment/v2. The plain /payment path accepts only POST; the delete operation for non-receipt collections lives on /v2, and takes the same query parameters this tool already sent.

• Receipts have no cancel operation. Invoices and proformas can be voided while keeping their number (/invoice/cancel, /estimate/cancel), but there is no /payment/cancel — a receipt can only be deleted, and only if it is the last one in its series.

• create_payment sends the internal note as observation, singular. Invoices and proformas spell the same field observations.

Document details live only in the PDF

No endpoint returns an invoice's issue date, client or line items. /invoice/paymentstatus gives three amounts and a paid flag; that is the whole of the structured data available about an issued document. Everything else exists only as rendered text inside the PDF.

get_invoice_pdf and get_estimate_pdf therefore default to as: "text" over HTTP, which extracts the text layer (via unpdf, no system dependency) and returns it — the only mode whose output a language model can inspect. The other modes:

• document returns the PDF as an MCP embedded resource (a binary blob the client receives, with mimeType: application/pdf). This is the way to deliver the actual file to a user over HTTP.

• file writes the PDF to SMARTBILL_DOWNLOAD_DIR on the machine running the server. Over HTTP that is a different machine, and nothing is served from that directory, so it is useful only for stdio, where client and server share a filesystem.

• base64 returns the raw bytes as a JSON string, for a programmatic caller.

send_document_email is an alternative for delivery: it has SmartBill mail the document to the client.

Amounts carry no currency

GET /invoice/paymentstatus returns invoiceTotalAmount, paidAmount and unpaidAmount as bare doubles. The documented response schema has no currency field, and the figures are in whatever currency the invoice was issued in — an EUR invoice returns the EUR amount, indistinguishable from a RON one.

Read unqualified next to a Romanian invoicing service, that reads as RON. It happened: a 1250 EUR invoice was reported as "1250 RON", understating it more than fivefold. get_invoice_payment_status therefore annotates its result with currency: "unknown" and a note, so the caveat sits beside the number rather than only in the tool description. get_invoice_pdf is the way to establish the actual currency.

What the API cannot do

There is no way to enumerate anything. The published API is 20 paths, and every document read — /invoice/paymentstatus, /invoice/pdf, /estimate/pdf, /estimate/invoices — is keyed by cif + seriesName + number. There is no search, no date range, no pagination, and no customer resource of any kind: clients are only ever written, as a nested block on a document, with saveToDb persisting them into the nomenclator with no read path back out.

So "all invoices for client ABC", "everything issued last month" and "list my customers" are not answerable through this API. /tax, /series and /stocks are the only endpoints that return a list. The server instructions tell the model this, so it reports the limitation instead of probing series numbers one at a time — which would also hit SmartBill's request rate limit.

In hosted mode with a database, the portal report tools answer exactly these questions by reading the web account through an authenticated session; without that configuration the limitation stands, and the instructions adapt to whichever set of tools is registered.

create_invoice_from_estimate sends useEstimateDetails: true with an estimate reference and no client block, letting SmartBill copy the client and line items from the proforma — this matches the documented exempluFacturaDinProforma shape.

License

MIT