ezBookkeeping MCP Server

An independent Model Context Protocol (MCP) server for the ezBookkeeping HTTP API. It supports stdio and Streamable HTTP transports.

MCP tools

File import/export, picture upload, user authentication management, and clear-all operations are intentionally excluded.

Related MCP server: banktivity-mcp

Requirements

• Node.js 20 or later

• An ezBookkeeping instance with API tokens enabled

• An ezBookkeeping API token

Read, write, batch, and delete flows have been verified against the official ezBookkeeping v1.6.1 Docker image.

Setup

cp .env.example .env
npm ci
npm run build

EZBK_BASE_URL=http://127.0.0.1:8080
EZBK_API_TOKEN=replace-with-api-token
EZBK_TIMEZONE=Asia/Tokyo

MCP_TRANSPORT=stdio
MCP_WRITE_PROFILE=read
MCP_CONFIRMATION_SECRET=

Profiles above read require an MCP_CONFIRMATION_SECRET of at least 32 characters.

Write profiles

Start with read and enable only the permissions you need.

Running

stdio

set -a
. ./.env
set +a
npm start

Example MCP client configuration:

{
  "mcpServers": {
    "ezbookkeeping": {
      "command": "node",
      "args": ["/absolute/path/to/ezbookkeeping-mcp/dist/index.js"],
      "env": {
        "EZBK_BASE_URL": "http://127.0.0.1:8080",
        "EZBK_API_TOKEN": "...",
        "EZBK_TIMEZONE": "Asia/Tokyo",
        "MCP_WRITE_PROFILE": "read"
      }
    }
  }
}

Streamable HTTP

MCP_TRANSPORT=http \
MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_ALLOWED_HOSTS=finance.example.com \
MCP_HTTP_BEARER_TOKEN="$(openssl rand -hex 32)" \
MCP_HTTP_PORT=3000 npm start

• MCP endpoint: http://HOST:3000/mcp

• Health check: http://HOST:3000/healthz

Non-loopback bindings require a bearer token, or an authenticated reverse proxy with MCP_HTTP_ALLOW_UNAUTHENTICATED=true. Do not expose the endpoint directly to the internet.

Docker Compose

cp .env.example .env
docker compose up --build -d
curl http://127.0.0.1:3000/healthz

Verification

npm run ci

Read-only smoke test against a real ezBookkeeping instance:

EZBK_BASE_URL=https://example.invalid \
EZBK_API_TOKEN=... \
npm run test:real

Safety

patch_transaction requires an expected_revision from a recent read. Batch updates and deletions revalidate the confirmation_token issued during Preview before Apply.

The ezBookkeeping API does not provide conditional writes, so revision validation and the upstream write are not fully atomic. Avoid updating the same transaction concurrently from the Web UI or another client. See SECURITY.md for HTTP exposure, secrets, and audit-log guidance.

License

MIT