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

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" }
    }
  }
}