e-Boekhouden Hybrid MCP Server

Connect Claude Desktop, Cursor, Antigravity, VS Code, Windsurf, Gemini CLI, or any local MCP-compatible assistant directly to your e-Boekhouden.nl administration. The server runs entirely on your local machine over standard I/O (stdio): no credentials pass through third-party servers, and all write operations require physical user presence verification.

Architectural Layers

The e-Boekhouden Hybrid MCP architecture integrates 4 complementary layers into a unified, secure accounting surface:

flowchart TD
    subgraph ClientLayer["AI Client Layer (Local stdio)"]
        AI["AI Assistant\n(Claude / Cursor / Antigravity / Copilot)"]
    end

    subgraph SecurityLayer["Layer 3: Hardware Security & Credential Store"]
        BioGate{"Native Biometric Gate\n(Windows Hello / Touch ID)"}
        KeyringStore[("OS Keyring / Credential Manager\n(Zero-Plaintext Storage)")]
    end

    subgraph MCPServer["e-Boekhouden Hybrid MCP Server (64 Tools)"]
        Registry["Tool Registry & Input Validation\n(Pydantic v2 Strict Bounds)"]
        
        subgraph L1["Layer 1: Core REST v1 Engine (49 Tools)"]
            RESTRead["34 Read Tools (Default)\n- Search & Batch Hydration\n- Financial Reports (Trial Balance, P&L, VAT, Aging)\n- Ledgers, Relations, Invoices, Mutations"]
            RESTWrite["15 Opt-in Write Tools\n- Create / Update / Delete\n- Required 'confirm: true'"]
        end

        subgraph L2["Layer 2: AI Bookkeeping Inbox & OCR"]
            DutchRules["Dutch Bookkeeping & VAT Rules\n(EU Art 226, EV Art 38, KIA, 80% Repr)"]
            Proposal["Booking Proposal Engine\n(Bonnetje vs Invoice Matching)"]
            BankClassify["Bank Statement Classifier\n(Ledger & VAT Code Suggestion)"]
        end

        subgraph L4["Layer 4: Modular Web Session Bridge (12 Tools)"]
            WebGrid["Import Grid & Bank Reconciliation"]
            WebArchive["Digital Archive (Mail & Herken) & OCR Model"]
            WebAttach["Document Linker (/folderkoppel) & Web Mutations"]
        end
    end

    subgraph RemoteAPI["External Accounting Services"]
        OfficialAPI["Official e-Boekhouden REST API\n(api.e-boekhouden.nl/v1/)"]
        WebSession["Internal Web Session Endpoints\n(secure20.e-boekhouden.nl)"]
    end

    AI <-->|MCP JSON-RPC over stdio| Registry
    KeyringStore -.->|Resolves Secret Token| Registry
    Registry --> L1
    Registry --> L2
    Registry --> L4
    RESTWrite -.->|Guarded by| BioGate
    WebAttach -.->|Guarded by| BioGate
    L1 -->|HTTPS Session| OfficialAPI
    L4 -->|Session Token| WebSession

1. Core REST v1 MCP Surface (49 Tools)

• 34 Read-Only Tools (Default): Fast search, bounded batch hydration, financial reports (Trial Balance, Profit & Loss, Balance Sheet, VAT summaries, AR/AP aging, ledger transactions), and resource inspection.

• 15 Opt-in Write Tools: Create invoices, book mutations, manage relations, products, ledgers, cost centers, and members. Every write requires explicit server configuration and client parameter confirmation.

2. AI Bookkeeping Inbox & OCR Classification (3 Tools)

• get_dutch_bookkeeping_rules: Authoritative Dutch tax rules, VAT decision trees (HOOG 21%, LAAG 9%, GEEN, VERL_INK reverse charge, EU Directive Art 226, Art 38 EV charging), receipt (bonnetje) detection heuristics, and Dutch tax deduction guidelines (KIA, 80% representation).

• prepare_booking_proposal: Automatically parses structured invoice/receipt metadata, cross-references live relations and ledger accounts in e-Boekhouden, and synthesizes balanced booking payloads for create_mutation or create_invoice.

• suggest_transaction_classification: Classifies raw bank statement descriptions, recommending appropriate debit/credit ledgers, VAT codes, and mutation types.

3. Native OS Biometric Hardware Gate & Keyring Store

• Hardware User Presence Verification: Any destructive or mutating operation (create_invoice, create_mutation, delete_*) triggers a native OS biometric prompt (Windows Hello face/fingerprint/PIN or macOS Touch ID / LocalAuthentication).

• Dynamic Context Prompts: Biometric modals display financial details in the prompt (e.g. Approve POST Invoice for EUR 1,250.00 to Relation 42?).

• Fail-Closed Design: Rejections, timeouts, or missing biometric hardware immediately abort the tool call before touching the remote API.

• OS Keyring Integration: Securely loads API tokens directly from Windows Credential Manager or macOS Keychain, eliminating plaintext tokens in .env files.

4. Modular Web Session Bridge (12 Tools)

• get_unprocessed_bank_transactions: Inspects unprocessed bank statements directly from e-Boekhouden's internal import grid.

• suggest_mutation_for_bank_statement: Queries the internal suggestion engine for pre-filled booking parameters.

• list_archive_folders: Lists Digital Archive folders (including Mail & Herken inbox folders) via /v1/api/folder/directory.

• list_archive_files: Lists files and Mail & Herken recognition status (menHStatus, koppelCount) inside a Digital Archive folder via /v1/api/folder/{folder_id}/filelist.

• get_recognized_invoice_model: Retrieves the internal AI OCR recognition model (mutatie, mutatieRegels, suggestedAiIban, suggestedAiBtwNr) for a Digital Archive file via /v1/api/mutatie/folder/{file_id}/model.

• get_mutation_model_by_number: Retrieves the editable web mutation model (mutatie, mutatieRegels, folderKoppelId) by mutation number (nr) via /v1/api/mutatie/nr/{mutation_number}/model.

• save_web_mutation: Creates or updates a mutation in the web UI format via POST /v1/api/mutatie, gated by enable_write_tools, confirm=True / confirm_write=True, and biometric verification.

• attach_file_to_mutation: Directly links uploaded digital archive receipts or invoices to journal mutations via /v1/api/folderkoppel/koppel/item.

• upload_archive_file: Uploads a local file from disk directly into a Digital Archive folder via POST /v1/api/folder/upload without streaming Base64 through LLM arguments.

• move_archive_files: Moves one or more Digital Archive files into a target folder via POST /v1/api/folder/bulk/update/{target_folder_id}.

• create_archive_folder: Creates a new Digital Archive folder via POST /v1/api/folder/directory.

• delete_web_mutations: Resolves mutation numbers (nr) to internal grid IDs via POST /v1/api/mutatie/gridtable and deletes them via POST /v1/api/mutatie/bulk/delete.

Related MCP server: Red MCP Server

Tool Catalog (64 Tools)

Security & Biometric Hardware Gate

The server enforces a rigorous triple-lock security model for mutating operations:

1. Lock 1 (Server Policy): Write tools are not registered or advertised to the AI assistant unless EBOEKHOUDEN_MCP_ENABLE_WRITE_TOOLS=true.

2. Lock 2 (Explicit AI Confirmation): Every write tool schema strictly requires confirm: true. The assistant must present the exact action, identifiers, and monetary values to the user and obtain affirmative consent.

3. Lock 3 (Native Hardware Biometrics): Before executing the write request against the e-Boekhouden API, the server invokes the host operating system's authentication layer:

   • Windows: Windows.Security.Credentials.UI.UserConsentVerifier (Windows Hello IR Camera, Fingerprint Sensor, or FIDO2 Security Key).

   • macOS: LocalAuthentication framework / Touch ID.

   • Linux / Headless: Fails closed unless biometric verification is explicitly disabled by the operator.

Testing Biometrics from the CLI

Verify your OS biometric setup without launching an MCP client:

# Windows
eboekhouden-mcp --test-biometric

# macOS
python -m eboekhouden_mcp.server --test-biometric

Keyring Credential Store Setup

Rather than storing your API secret token in plaintext in .env files, use your operating system's credential vault:

Windows Credential Manager

# Store token securely in Windows Credential Manager
python -c "import keyring; keyring.set_password('eboekhouden_mcp', 'secret_token', 'your-secret-api-token-here')"

macOS Keychain

# Store token securely in macOS Keychain
python3 -c "import keyring; keyring.set_password('eboekhouden_mcp', 'secret_token', 'your-secret-api-token-here')"

When configured, the MCP server automatically resolves the token on startup without requiring EBOEKHOUDEN_MCP_SECRET_TOKEN in the environment.

Configuration

Settings are configured via environment variables or a .env file in the working directory:

AI Client Configuration

Antigravity & Gemini CLI

Add to your mcp_config.json (e.g. ~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "eboekhouden": {
      "command": "/path/to/eboekhouden-mcp/.venv/Scripts/eboekhouden-mcp.exe",
      "args": []
    }
  }
}

Or via Python module:

{
  "mcpServers": {
    "eboekhouden": {
      "command": "/path/to/eboekhouden-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "eboekhouden_mcp.server"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "eboekhouden": {
      "command": "/path/to/eboekhouden-mcp/.venv/bin/eboekhouden-mcp",
      "args": [],
      "env": {
        "EBOEKHOUDEN_MCP_ENABLE_WRITE_TOOLS": "false",
        "EBOEKHOUDEN_MCP_REQUIRE_BIOMETRIC": "true"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json or Global MCP Settings:

{
  "mcpServers": {
    "eboekhouden": {
      "command": "python",
      "args": ["-m", "eboekhouden_mcp.server"],
      "env": {
        "EBOEKHOUDEN_MCP_ENABLE_WRITE_TOOLS": "true",
        "EBOEKHOUDEN_MCP_REQUIRE_BIOMETRIC": "true"
      }
    }
  }
}

Claude Code

claude mcp add-json --scope user eboekhouden \
  '{"type":"stdio","command":"/path/to/eboekhouden-mcp/.venv/bin/eboekhouden-mcp","args":[]}'

Quick Start

1. Installation

Requires Python 3.10+ and uv or standard virtual environments:

# Clone the repository
git clone https://github.com/hemelbesem90s/e-Boekhouden-MCP.git
cd e-Boekhouden-MCP

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate    # On Windows: .\.venv\Scripts\Activate.ps1
uv pip install -e ".[dev]"

2. Configure Token

Using Keyring (Recommended):

python -c "import keyring; keyring.set_password('eboekhouden_mcp', 'secret_token', 'your-token-here')"

Or copy .env.example to .env:

cp .env.example .env
# Edit .env and supply your EBOEKHOUDEN_MCP_SECRET_TOKEN

3. Verify Configuration

eboekhouden-mcp --check-config

4. Run the Test Suite

pytest --cov

All 155 unit and integration tests run fully mocked without contacting live API endpoints or requiring production secrets.

Credits & Attribution

This project is built upon the open-source innovations of the Dutch accounting and MCP developer communities. Special recognition and attribution go to:

1. matisup10/e-Boekhouden-MCP

• Author: matisup10 and contributors (MIT License)

• Foundational Architecture:

  • 49-tool core REST v1 MCP server architecture and tool schemas.

  • Robust e-Boekhouden REST API client with full Pydantic v2 domain models.

  • High-performance batch hydration, compact search algorithms, and financial report aggregators (Trial Balance, P&L, VAT summary, AR/AP aging).

  • Explicit confirm: true write-action security pattern.

2. JoooostB/speedy-eboekhouden

• Author: Joost and contributors (MIT License)

• Foundational Accounting Logic & Session Schemas:

  • Authoritative Dutch bookkeeping domain heuristics and structured OCR prompt engineering.

  • Dutch VAT decision tree (EU VAT Directive Art. 226 reverse-charge, Art. 38 EV charging, KIA investment allowances, 80% representation limits).

  • Receipt (bonnetje) detection heuristics and automatic ledger cross-referencing.

  • Reverse-engineered internal web session API schemas for bank import statements and /folderkoppel attachment linking.

3. Gemini Argon (Google DeepMind — Antigravity)

• Role: Co-Architect & Agentic Engineering Partner

• Hybrid Integration & Security Engineering:

  • Unified 4-layer hybrid MCP architecture combining the REST v1 accounting engine, AI Bookkeeping Inbox, OS Keyring credential vault, and 12-tool Web Session Bridge.

  • Native OS biometric hardware presence gate (Windows Hello WinRT UserConsentVerifier with foreground window focus & macOS Touch ID LocalAuthentication).

  • Automatic web-mutation payload normalization (MUT_026, MUT_112, MUT_117, MutNr) and fail-closed Digital Archive upload/management tooling.

See the NOTICE and LICENSE files for complete license texts and third-party copyright notices.

License

Released under the MIT License.