e-Boekhouden Hybrid MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
Bring your own e-Boekhouden API token. This independent community project is licensed under the MIT License and is not affiliated with or endorsed by e-Boekhouden.nl.
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 (83 Tools)"]
Registry["Tool Registry & Input Validation\n(Pydantic v2 Strict Bounds)"]
subgraph L1["Layer 1: Core REST v1 & Power Reports (51 Tools)"]
RESTRead["36 Read Tools (Default)\n- Search & Batch Hydration\n- Financial Reports (Trial Balance, P&L, Cashflow, Budgets, 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 (29 Tools)"]
WebGrid["Import Grid, Bank Reconciliation & Urenregistratie (WIP Hours)"]
WebArchive["Digital Archive (Mail & Herken), Quotes & Invoice Email Dispatch"]
WebAttach["Document Linker (/folderkoppel), Web Mutations & Commercial Quotes"]
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| WebSession1. Core REST v1 & Power Reports Surface (51 Tools)
36 Read-Only Tools (Default): Fast search, bounded batch hydration, financial reports (Trial Balance, Profit & Loss, Balance Sheet, Cashflow, Budgets vs. Actuals, VAT summaries, AR/AP aging, ledger transactions), and resource inspection.
15 Opt-in Write Tools: Create invoices (including immediate email dispatch via
email_template_id/email, automatic debtor mutation booking viamutation, and line-item units/codes/discounts), book mutations, and 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 forcreate_mutationorcreate_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
.envfiles.
4. Modular Web Session Bridge (29 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 viaPOST /v1/api/mutatie, gated byenable_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 viaPOST /v1/api/folder/uploadwithout streaming Base64 through LLM arguments.move_archive_files: Moves one or more Digital Archive files into a target folder viaPOST /v1/api/folder/bulk/update/{target_folder_id}.create_archive_folder: Creates a new Digital Archive folder viaPOST /v1/api/folder/directory.delete_web_mutations: Resolves mutation numbers (nr) to internal grid IDs viaPOST /v1/api/mutatie/gridtableand deletes them viaPOST /v1/api/mutatie/bulk/delete.list_time_entries: Fetches logged hours and uninvoiced WIP from e-BoekhoudenUrenregistratie(/v1/api/uur/factureren/gridtable) with automatic 50-row pagination and a per-project financial summary (hours,kilometers,total_excl_vat,total_vat,total_incl_vat).list_time_projects: Lists time-tracking projects and their linked client relations (/v1/api/project/getalland/v1/api/project/gridtable).list_time_activities: Lists time-tracking activities, hourly/kilometer rates, VAT codes, and revenue ledgers (/v1/api/activiteit/getall).create_time_project: Creates a time-tracking project in e-Boekhouden viaPOST /v1/api/project, supporting customer relation linking, hourly/km billing rates, and automatic 6-digit revenue ledger code resolution (e.g.810200,810300).update_time_project: Updates or deactivates an existing time project viaPUT /v1/api/project(supports marking completed projects inactive withactive=False).create_time_entry: Logs a time entry inUrenregistratieviaPOST /v1/api/uurspecifying project, activity, hours, date, billable status, and optional notes/km.update_time_entry: Updates an existing time entry inUrenregistratieviaPUT /v1/api/uur(hours, date, project, activity, notes, billable status).delete_time_entry: Deletes a time entry fromUrenregistratieviaDELETE /v1/api/uur/{entry_id}.invoice_time_entries: Converts unbilled time entries into an invoice viaPOST /v1/api/uur/factureren, with optional atomic customer reference (kenmerk) and invoice text (factuurtekst) post-update and PDF regeneration.update_invoice: Updates outbound invoice headers (kenmerk,factuurtekst, date, payment term days, template) viaPUT /v1/api/factuur/modeland triggers invoice PDF regeneration viaGET /v1/api/factuur/pdfinvoiceschedule.list_quotes: Lists commercial quotes (offertes) from/v1/api/offerte/gridtablewith optional filters and metadata (available statuses, templates, users, and next quote number).get_quote: Retrieves full quote details byquote_idorquote_number, including line items (offerteregel), dashboard metadata, and attached Digital Archive PDFs.create_quote: Creates a commercial quote (offerte) viaPOST /v1/api/offerte, inserts line items viaPOST /v1/api/offerteregel(with automatic VAT and revenue ledger resolution), and optionally links an uploaded branded PDF from the Digital Archive.update_quote: Updates an existing quote's status (e.g.01. Ingevoerd→02. Verzonden→04. Geaccepteerd), dates, notes, line items, or linked Digital Archive PDF.attach_file_to_quote: Links an uploaded Digital Archive file (such as a branded PDF offer) to a quote viaPOST /v1/api/folderkoppel/koppel/item(koppelType="OF").delete_quote: Deletes a quote by ID viaDELETE /v1/api/offerte/{quote_id}.send_invoice: Dispatches an existing invoice by email viaPOST /v1/api/factuur/mailafter rendering merge fields (returning sender details, email template ID, and rendered body text), gated byconfirm=Trueand biometric verification.whitelist_web_session_ip: Authorizes a new or unrecognized IP address in e-Boekhouden viaPOST /v1/api/loginwhitelist/whitelistusing the verification code or approval URL sent by email.
Related MCP server: manager-mcp
Tool Catalog (84 Tools)
Category | Read Tools (Enabled by Default) | Write Tools (Gated by Double-Lock + Biometrics) |
Relations |
|
|
Invoices |
|
|
Mutations |
|
|
Products |
|
|
Ledgers |
|
|
Cost Centers |
|
|
Members |
|
|
Administration |
| — |
Templates & Units |
| — |
Financial Reports |
| — |
AI Bookkeeping Inbox |
| — |
Digital Archive | — |
|
Web Session Bridge |
|
|
Security & Biometric Hardware Gate
The server enforces a rigorous triple-lock security model for mutating operations:
Lock 1 (Server Policy): Write tools are not registered or advertised to the AI assistant unless
EBOEKHOUDEN_MCP_ENABLE_WRITE_TOOLS=true.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.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:
LocalAuthenticationframework / 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-biometricCloud Storage Hydration Protection (Fail-Closed)
To safeguard local virtual file provider sync engines from freezing or recursive file locks during automated archive processing, upload_archive_file enforces fail-closed path validation:
Rejected Paths:
macOS File Provider cloud mounts (
~/Library/CloudStorage/..., covering Google DriveMy Drive&Shared drives, OneDrive, Dropbox, Box)macOS iCloud Drive (
~/Library/Mobile Documents/...)macOS
/Volumes/Google DriveWindows
H:\Shared drives,G:\Cloud provider folders (
OneDrive,Dropbox)UNC network shares (
\\...,//...)
Allowed Local Staging: Binary documents must be copied or staged into local temporary directories (e.g.
/tmp,$TMPDIRon macOS/Linux, orC:\Temp\on Windows) before uploading.
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 REST API token securely in Windows Credential Manager
eboekhouden-mcp --set-secret-token "your-secret-api-token-here"
# Optional: Store Web Session login credentials for automatic 5-day JWT renewal
eboekhouden-mcp --set-web-credentials "your-username" "your-password"
eboekhouden-mcp --refresh-web-tokenmacOS Keychain
# Store REST API token securely in macOS Keychain (with non-prompting -A ACL)
eboekhouden-mcp --set-secret-token "your-secret-api-token-here"
# Optional: Store Web Session login credentials for automatic 5-day JWT renewal
eboekhouden-mcp --set-web-credentials "your-username" "your-password"
eboekhouden-mcp --refresh-web-token
# Optional: Store IMAP credentials for autonomous IP whitelisting
eboekhouden-mcp --set-imap-credentials "imap.gmail.com" "jacob@grobler.nl" "your-app-password"
# Optional: Whitelist current IP manually via code/URL or automatically via email poll
eboekhouden-mcp --whitelist-ip "https://secure20.e-boekhouden.nl/overig/login-whitelist?code=ABC123XYZ"
eboekhouden-mcp --auto-whitelist-ipWhen web_username and web_password are stored in Keyring, WebSessionClient automatically logs in via POST /v1/api/auth/login whenever a session token is missing or expires (HTTP 401 / SECURITY_010), persists the fresh web_session_token back to Keyring, and retries the request transparently.
Autonomous New-IP Whitelisting Bridge
Whenever e-Boekhouden detects a login from a new or unrecognized IP address, it halts immediate login and dispatches a verification link to your registered email address. With auto_whitelist_ip: true (default), WebSessionClient:
Intercepts the IP authorization challenge non-destructively.
Polls your IMAP inbox using
BODY.PEEK(preserving theUNSEENstatus of your email so messages remain unread).Extracts the approval link/code and automatically submits it via
POST /v1/api/loginwhitelist/whitelist.Completes login and returns the fresh JWT
auth-tokento your MCP client without manual intervention.
Configuration
Settings are configured via environment variables or a .env file in the working directory:
Environment Variable | Required | Default | Description |
| Yes* | — | e-Boekhouden REST API token (*Optional if stored in Keyring) |
| No |
| Expose create, update, and delete tools |
| No |
| Enforce native Windows Hello / Touch ID biometric challenge on writes |
| No |
| Seconds biometric verification remains valid for batch writes ( |
| No |
| Service name used for OS Keyring lookup |
| No |
| Enable web session bridge tools (bank import grid, attachment linking) |
| No | — | Session authentication token for web session endpoints (or auto-managed via Keyring) |
| No | — | Web login username for automatic session renewal (*Optional if stored in Keyring as |
| No | — | Web login password for automatic session renewal (*Optional if stored in Keyring as |
| No | — | Optional Base32 TOTP secret if 2FA is enabled (*Optional if stored in Keyring as |
| No |
| Base URL for internal web session requests |
| No | — | Optional HTTP or SOCKS5 proxy URL (e.g. |
| No |
| Enable autonomous IMAP polling & IP whitelisting on new-IP email challenges |
| No |
| IMAP server for auto-whitelisting (*Falls back to Keyring |
| No | — | IMAP username/email for auto-whitelisting (*Falls back to Keyring |
| No | — | IMAP password or app password for auto-whitelisting (*Falls back to Keyring |
| No |
| Official e-Boekhouden REST API endpoint |
| No |
| Restrict connections strictly to official API host unless set to |
| No |
| Source identifier logged with API requests |
| No |
| Diagnostics level logged to stderr ( |
| No |
| Enable Microsoft Graph digital archive mailbox delivery |
| Archive only | — | Local directory path allowlisted for archive reading |
AI Client Configuration
Antigravity & Gemini CLI
Add to your mcp_config.json (e.g. ~/.gemini/config/mcp_config.json):
macOS / Linux:
{
"mcpServers": {
"eboekhouden": {
"command": "/path/to/eboekhouden-mcp/.venv/bin/eboekhouden-mcp",
"args": []
}
}
}Windows:
{
"mcpServers": {
"eboekhouden": {
"command": "C:/path/to/eboekhouden-mcp/.venv/Scripts/eboekhouden-mcp.exe",
"args": []
}
}
}Or via Python module:
{
"mcpServers": {
"eboekhouden": {
"command": "/path/to/eboekhouden-mcp/.venv/bin/python",
"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_TOKEN3. Verify Configuration
eboekhouden-mcp --check-config4. Run the Test Suite
pytest --covAll 183 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: truewrite-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
/folderkoppelattachment 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 22-tool Web Session Bridge.
Native OS biometric hardware presence gate (Windows Hello WinRT
UserConsentVerifierwith foreground window focus & macOS Touch IDLocalAuthentication).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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Connect Claude to Dutch accounting software: e-Boekhouden invoices, contacts and ledgers.
e-Boekhouden MCP server for ChatGPT, Claude and any AI agent: create invoice, book mutation, add relation, list open items and export ledger in your own e-Boekhouden account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to e-Boekhouden yourself; Cotlet does not store your password and you need no e-Boekhouden API key. About the official e-Boekhouden API: Yes. e-Boekhouden has a REST API with an OpenAPI description (checked 14 Oct 2026). Setup and FAQ: https://cotlet.dev/integrations/e-boekhouden-api-mcp-server
Read e-Boekhouden relations, invoices, ledgers, bookings and products; create relations, invoices.
AI accounting: ask about your live AccountsOS books in plain English. Read-only tools for transactions, cash balances, invoices, bills, VAT, filing deadlines and reports across 32 countries. OAuth sign-in; free 14-day trial at accounts-os.com.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with direct access to HLedger accounting data and functionality, enabling natural language queries for balances, reports, journal entries, and financial analysis.22 npm65MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to query and manage self-hosted accounting data—invoices, balances, and books—through natural language, with read-only tools by default and optional scoped write operations.3024 PyPI1AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to read and write accounting data in PowerOffice Go, including bookkeeping, sales, purchases, payroll, time tracking, and read-only bank access, with support for multiple companies and strict isolation.MIT
- FlicenseNot gradedqualityBmaintenanceConnects AI assistants to the official DATEV APIs so users can query bookkeeping, payroll, and documents in plain language; any write is previewed and requires a matching one-time confirmation before it is executed.-