cebelca-mcp

An MCP server that wraps the cebelca.biz accounting API, exposing it as tools an MCP client (Claude, etc.) can call.

Development

This project uses devenv for its development environment (Node.js, yarn). With direnv installed, cd into the directory and the environment loads automatically; otherwise run devenv shell.

The cebelca.biz API key is read from the CEBELCA_BIZ_API_KEY environment variable. It is set in .envrc (git-ignored) and loaded by direnv/devenv. The server refuses to start if the variable is missing.

Optional: CEBELCA_BIZ_BASE_URL overrides the API base URL (defaults to https://www.cebelca.biz/API).

Commands

yarn install     # install dependencies
yarn dev         # run from source with tsx (no build step)
yarn build       # compile TypeScript to dist/
yarn start       # run the compiled server (dist/index.js)
yarn typecheck   # type-check without emitting

Project layout

src/
  index.ts    Entry point: builds the server, connects over stdio.
  config.ts   Loads config from the environment (API key, base URL).
  client.ts   HTTP client for the cebelca.biz resource/method API.
  tools.ts    MCP tool registration. Add new tools here.

The cebelca.biz API

The API is a resource/method RPC over HTTP (docs: Workonomic-API-bash, making-an-invoice):

• Every call is an HTTP POST with x-www-form-urlencoded arguments.
• Resource and method go in the _r and _m query params (_m2 stacks a second method, _f picks the output format, _x=1 is explore mode).
• Auth is HTTP Basic: the API token is the username, the password is the literal x.
• Success responses look like ["ok", [{...}]] or [[{...}]]; errors like ["validation", {...}] or [[{"err": "..."}]]. CebelcaClient unwraps the success payload and throws CebelcaError on failures.
• PDFs come from a separate .../API-pdf endpoint.

Tools

Tool	Purpose
cebelca_explore	Discover resources / methods / arguments (explore mode).
cebelca_call	Generic escape hatch: call any resource/method directly.
cebelca_assure_partner	Find-or-create a partner, return its id.
cebelca_create_invoice_head	Create an issued-invoice head (insert-smart-2).
cebelca_add_invoice_line	Add a body line to an invoice.
cebelca_mark_invoice_paid	Mark an invoice paid (by id or external id).
cebelca_finalize_invoice	Issue an invoice — noncash or fiscal (FURS).
cebelca_get_fiscal_info	Fetch ZOI/EOR/QR fiscal details.
cebelca_create_proforma_head	Create a proforma (pre-invoice) head.
cebelca_add_proforma_line	Add a body line to a proforma.
cebelca_proforma_to_invoice	Convert a proforma into an invoice.
cebelca_get_pdf	Fetch a document PDF as a base64 resource.

Adding tools

Register new tools in src/tools.ts via server.registerTool(...), using CebelcaClient.call(resource, method, args) and the run helper to turn responses (and CebelcaErrors) into MCP tool results. When you need an operation no dedicated tool covers, cebelca_explore + cebelca_call reach the whole API.

Using with an MCP client

Build first (yarn build), then point your client at the compiled entry:

{
  "mcpServers": {
    "cebelca": {
      "command": "node",
      "args": ["/absolute/path/to/cebelca-mcp/dist/index.js"],
      "env": { "CEBELCA_BIZ_API_KEY": "your-key-here" }
    }
  }
}