Skip to main content
Glama
ezbookkeeping-mcp-server

ezbookkeeping-mcp-server

by abco20

ezBookkeeping MCP Server

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

MCP tools

Domain

Tools

Minimum profile

System

get_server_info

read

Transactions

search_transactions, get_transaction

read

Transactions

create_transaction, patch_transaction

standard

Batch

preview_transaction_batch, apply_transaction_batch

standard

Delete

delete_transaction

standard

Accounts

list_accounts

read

Accounts

manage_account

extended (admin for deletion)

Categories

list_categories

read

Categories

manage_category

extended

Tags

list_tag_groups, list_tags

read

Tags

manage_tag_group, manage_tag

extended

Templates

list_templates

read

Templates

manage_template

extended

Analytics

get_financial_summary, get_financial_trends, get_reconciliation_statement

read

Exchange rates

get_exchange_rates

read

Exchange rates

manage_custom_exchange_rate

extended

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

Profile

Permissions

read

Read and analytics only

standard

Create, update, delete, and batch-update transactions

extended

standard plus master data, templates, and custom exchange rates

admin

extended plus account deletion

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

Available Tools

23 tools
apply_transaction_batchApply batch transaction updateA

Apply a previously previewed batch operation. Every target revision is checked again before writing.

Inputs: confirmation_token (required).

create_transactionCreate transactionC

Create an income, expense, transfer or balance modification transaction. Requires standard write profile.

Inputs: type (required), source_amount (required), source_account (required), tags, +9 more.

delete_transactionDelete transactionA

Preview or apply deletion of one transaction. Apply requires a signed confirmation token.

Inputs: mode (required), transaction_id (required), confirmation_token.

get_exchange_ratesGet exchange ratesA

Return latest upstream and user-custom exchange rates.

Inputs: no named parameters.

get_financial_summaryGet financial summaryC

Return period totals and category/account breakdown using ezBookkeeping server-side statistics.

Inputs: end_time (required), start_time (required), keyword, ignore_case, +1 more.

get_reconciliation_statementGet reconciliation statementB

Return account opening/closing balances and transaction running balances for reconciliation.

Inputs: account (required), end_time, start_time.

get_server_infoGet ezBookkeeping server informationA

Return upstream version information and enabled MCP write capabilities.

Inputs: no named parameters.

get_transactionGet transactionB

Get one transaction by ID with a revision hash.

Inputs: transaction_id (required).

list_accountsList accountsA

List all accounts and subaccounts with IDs, balances and hierarchy paths.

Inputs: include_hidden.

list_categoriesList transaction categoriesB

List income, expense and transfer category trees.

Inputs: type, include_hidden.

list_tag_groupsList tag groupsB

List transaction tag groups.

Inputs: no named parameters.

list_tagsList tagsB

List all transaction tags with group names.

Inputs: include_hidden.

list_templatesList transaction templatesA

List normal or scheduled transaction templates.

Inputs: template_type.

manage_accountManage accountC

Create, update, hide, unhide, reorder or delete accounts. Account deletion requires admin profile and Preview/Apply.

Inputs: operation (required), mode, patch, orders, +3 more.

manage_categoryManage transaction categoryB

Create, update, hide, unhide, reorder or delete transaction categories. Delete uses Preview/Apply.

Inputs: operation (required), mode, patch, orders, +3 more.

manage_custom_exchange_rateManage custom exchange rateA

Set or delete a user custom exchange rate. Requires extended write profile.

Inputs: currency (required), operation (required), rate.

manage_tagManage tagB

Create, update, hide, unhide, reorder or delete tags. Delete uses Preview/Apply.

Inputs: operation (required), tag, mode, patch, +3 more.

manage_tag_groupManage tag groupB

Create, rename, reorder or delete a tag group. Delete uses Preview/Apply.

Inputs: operation (required), mode, group, patch, +3 more.

manage_templateManage transaction templateC

Create, update, hide, unhide, reorder or delete normal and scheduled transaction templates.

Inputs: operation (required), mode, patch, orders, +4 more.

patch_transactionPatch transactionA

Safely update selected transaction fields while preserving all unspecified fields. Supply expected_revision from get/search to prevent lost updates.

Inputs: patch (required), transaction_id (required), expected_revision (required).

preview_transaction_batchPreview batch transaction updateB

Preview one batch category, tag or account update and receive a signed confirmation token.

Inputs: selector (required), operation (required).

search_transactionsSearch transactionsC

Search ezBookkeeping transactions. Results include stable IDs, full tag data, editability and a revision hash for safe updates.

Inputs: type, limit, cursor, keyword, +12 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools target distinct resources/actions, with clear separation between list/get/manage. Minor overlap exists between list_tags and list_tag_groups, and between get_financial_summary/trends/reconciliation, but descriptions differentiate purposes.

    Naming Consistency4/5

    Follows a consistent snake_case verb_noun pattern (e.g., list_accounts, create_transaction), with some singular/plural inconsistency and the manage_* tools combining multiple operations. Overall predictable and readable.

    Tool Count4/5

    At 23 tools, this is on the heavy side but each tool maps to a distinct entity or operation in the bookkeeping domain. The breadth is justified by the variety of resources (accounts, categories, tags, templates, transactions, exchange rates) and features.

    Completeness5/5

    Provides comprehensive lifecycle coverage: CRUD for accounts, categories, tags, tab groups, templates, transactions, plus reporting, exchange rates, and batch operations. No obvious missing operations for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server to interact with the Cuéntica accounting API, allowing users to manage invoices, expenses, income, clients, providers, and bank accounts via natural language.
      59
      31 PyPI
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for accessing and managing Banktivity personal finance data, enabling account, transaction, and budget operations through natural language.
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for interacting with Money Manager EX databases. Enables querying and managing financial data like accounts, transactions, payees, categories, currencies, and more through natural language.
      68
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for personal finance management. Enables natural language expense logging, budgeting, recurring charge detection, and statement import with deterministic local calculations.
      -