e-Boekhouden Hybrid MCP Server
README.md
<p align="center">
<img src="docs/assets/logo.svg" width="128" height="128" alt="e-Boekhouden MCP logo">
</p>
<h1 align="center">e-Boekhouden Hybrid MCP Server</h1>
<p align="center">
A secure, local Model Context Protocol (MCP) server combining the complete 49-tool REST v1 e-Boekhouden engine with AI bookkeeping heuristics, Dutch VAT classification, native OS biometric hardware gating (Windows Hello & Touch ID), and an optional web session bridge.
</p>
<p align="center">
<img src="https://img.shields.io/badge/Python-3.10--3.13-3776AB?logo=python&logoColor=white" alt="Python 3.10 through 3.13">
<img src="https://img.shields.io/badge/MCP-stdio%20%7C%2084%20Tools-147D64" alt="MCP stdio 84 Tools">
<img src="https://img.shields.io/badge/Biometric%20Gate-Windows%20Hello%20%7C%20Touch%20ID-blueviolet" alt="Biometric Hardware Gate">
<img src="https://img.shields.io/badge/Credential%20Store-Keyring%20%2F%20Keychain-0078D4" alt="OS Keyring Integration">
<img src="https://img.shields.io/badge/Coverage-82%25-brightgreen" alt="82% Test Coverage">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2E7D32" alt="MIT license"></a>
</p>
<p align="center">
<a href="#architectural-layers">Architecture</a> ·
<a href="#quick-start">Quick start</a> ·
<a href="#ai-client-configuration">AI assistants</a> ·
<a href="#tool-catalog-84-tools">Tool catalog</a> ·
<a href="#security--biometric-hardware-gate">Biometric security</a> ·
<a href="#configuration">Configuration</a> ·
<a href="#credits--attribution">Credits & Attribution</a>
</p>
---
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.
> [!IMPORTANT]
> 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:
```mermaid
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| WebSession
```
### 1. 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 via `mutation`, 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 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 (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 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`.
- `list_time_entries`: Fetches logged hours and uninvoiced WIP from e-Boekhouden `Urenregistratie` (`/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/getall` and `/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 via `POST /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 via `PUT /v1/api/project` (supports marking completed projects inactive with `active=False`).
- `create_time_entry`: Logs a time entry in `Urenregistratie` via `POST /v1/api/uur` specifying project, activity, hours, date, billable status, and optional notes/km.
- `update_time_entry`: Updates an existing time entry in `Urenregistratie` via `PUT /v1/api/uur` (hours, date, project, activity, notes, billable status).
- `delete_time_entry`: Deletes a time entry from `Urenregistratie` via `DELETE /v1/api/uur/{entry_id}`.
- `invoice_time_entries`: Converts unbilled time entries into an invoice via `POST /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) via `PUT /v1/api/factuur/model` and triggers invoice PDF regeneration via `GET /v1/api/factuur/pdfinvoiceschedule`.
- `list_quotes`: Lists commercial quotes (*offertes*) from `/v1/api/offerte/gridtable` with optional filters and metadata (available statuses, templates, users, and next quote number).
- `get_quote`: Retrieves full quote details by `quote_id` or `quote_number`, including line items (`offerteregel`), dashboard metadata, and attached Digital Archive PDFs.
- `create_quote`: Creates a commercial quote (*offerte*) via `POST /v1/api/offerte`, inserts line items via `POST /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 via `POST /v1/api/folderkoppel/koppel/item` (`koppelType="OF"`).
- `delete_quote`: Deletes a quote by ID via `DELETE /v1/api/offerte/{quote_id}`.
- `send_invoice`: Dispatches an existing invoice by email via `POST /v1/api/factuur/mail` after rendering merge fields (returning sender details, email template ID, and rendered body text), gated by `confirm=True` and biometric verification.
- `whitelist_web_session_ip`: Authorizes a new or unrecognized IP address in e-Boekhouden via `POST /v1/api/loginwhitelist/whitelist` using the verification code or approval URL sent by email.
---
## Tool Catalog (84 Tools)
| Category | Read Tools (Enabled by Default) | Write Tools (Gated by Double-Lock + Biometrics) |
|---|---|---|
| **Relations** | `list_relations`, `get_relation`, `search_relations`, `get_relations_batch` | `create_relation`, `update_relation`, `delete_relation` |
| **Invoices** | `list_invoices`, `get_invoice`, `search_invoices`, `get_invoices_batch` | `create_invoice`, `update_invoice`, `send_invoice` |
| **Mutations** | `list_mutations`, `get_mutation`, `list_outstanding_invoices`, `search_mutations`, `get_mutations_batch` | `create_mutation` |
| **Products** | `list_products`, `get_product`, `list_product_groups` | `create_product`, `update_product`, `delete_product` |
| **Ledgers** | `list_ledgers`, `get_ledger`, `get_ledger_balance` | `create_ledger`, `update_ledger` |
| **Cost Centers** | `list_cost_centers`, `get_cost_center` | `create_cost_center`, `delete_cost_center` |
| **Members** | `list_members`, `get_member` | `create_member`, `delete_member` |
| **Administration** | `list_administrations`, `list_linked_administrations` | — |
| **Templates & Units**| `list_invoice_templates`, `list_email_templates`, `list_units` | — |
| **Financial Reports** | `get_trial_balance`, `get_profit_loss`, `get_balance_sheet`, `get_vat_summary`, `get_ar_ap_aging`, `get_ledger_transactions`, `get_cash_flow`, `get_budget_vs_actuals` | — |
| **AI Bookkeeping Inbox** | `get_dutch_bookkeeping_rules`, `prepare_booking_proposal`, `suggest_transaction_classification` | — |
| **Digital Archive** | — | `send_file_to_digital_archive` |
| **Web Session Bridge** | `get_unprocessed_bank_transactions`, `suggest_mutation_for_bank_statement`, `list_archive_folders`, `list_archive_files`, `get_recognized_invoice_model`, `get_mutation_model_by_number`, `list_time_entries`, `list_time_projects`, `list_time_activities`, `list_quotes`, `get_quote`, `whitelist_web_session_ip` | `attach_file_to_mutation`, `save_web_mutation`, `upload_archive_file`, `move_archive_files`, `create_archive_folder`, `delete_web_mutations`, `create_time_project`, `update_time_project`, `create_time_entry`, `update_time_entry`, `delete_time_entry`, `invoice_time_entries`, `update_invoice`, `create_quote`, `update_quote`, `attach_file_to_quote`, `delete_quote`, `send_invoice` |
---
## 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:
```powershell
# Windows
eboekhouden-mcp --test-biometric
```
```bash
# macOS
python -m eboekhouden_mcp.server --test-biometric
```
### Cloud 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 Drive `My Drive` & `Shared drives`, OneDrive, Dropbox, Box)
- macOS iCloud Drive (`~/Library/Mobile Documents/...`)
- macOS `/Volumes/Google Drive`
- Windows `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`, `$TMPDIR` on macOS/Linux, or `C:\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
```powershell
# 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-token
```
### macOS Keychain
```bash
# 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-ip
```
When `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`:
1. Intercepts the IP authorization challenge non-destructively.
2. Polls your IMAP inbox using `BODY.PEEK` (preserving the `UNSEEN` status of your email so messages remain unread).
3. Extracts the approval link/code and automatically submits it via `POST /v1/api/loginwhitelist/whitelist`.
4. Completes login and returns the fresh JWT `auth-token` to 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 |
|---|:---:|:---:|---|
| `EBOEKHOUDEN_MCP_SECRET_TOKEN` | Yes* | — | e-Boekhouden REST API token (*Optional if stored in Keyring) |
| `EBOEKHOUDEN_MCP_ENABLE_WRITE_TOOLS` | No | `false` | Expose create, update, and delete tools |
| `EBOEKHOUDEN_MCP_REQUIRE_BIOMETRIC` | No | `true` | Enforce native Windows Hello / Touch ID biometric challenge on writes |
| `EBOEKHOUDEN_MCP_BIOMETRIC_TTL_SECONDS` | No | `300` | Seconds biometric verification remains valid for batch writes (`0` = prompt every call) |
| `EBOEKHOUDEN_MCP_KEYRING_SERVICE` | No | `eboekhouden_mcp` | Service name used for OS Keyring lookup |
| `EBOEKHOUDEN_MCP_ENABLE_WEB_SESSION` | No | `false` | Enable web session bridge tools (bank import grid, attachment linking) |
| `EBOEKHOUDEN_MCP_WEB_SESSION_TOKEN` | No | — | Session authentication token for web session endpoints (or auto-managed via Keyring) |
| `EBOEKHOUDEN_MCP_WEB_USERNAME` | No | — | Web login username for automatic session renewal (*Optional if stored in Keyring as `web_username`) |
| `EBOEKHOUDEN_MCP_WEB_PASSWORD` | No | — | Web login password for automatic session renewal (*Optional if stored in Keyring as `web_password`) |
| `EBOEKHOUDEN_MCP_WEB_TOTP_SECRET` | No | — | Optional Base32 TOTP secret if 2FA is enabled (*Optional if stored in Keyring as `web_totp_secret`) |
| `EBOEKHOUDEN_MCP_WEB_SESSION_BASE_URL` | No | `https://secure20.e-boekhouden.nl` | Base URL for internal web session requests |
| `EBOEKHOUDEN_MCP_WEB_PROXY` | No | — | Optional HTTP or SOCKS5 proxy URL (e.g. `socks5://127.0.0.1:1080`) for fixed egress IP routing |
| `EBOEKHOUDEN_MCP_AUTO_WHITELIST_IP` | No | `true` | Enable autonomous IMAP polling & IP whitelisting on new-IP email challenges |
| `EBOEKHOUDEN_MCP_IMAP_SERVER` | No | `imap.gmail.com` | IMAP server for auto-whitelisting (*Falls back to Keyring `grobler_gmail`) |
| `EBOEKHOUDEN_MCP_IMAP_USERNAME` | No | — | IMAP username/email for auto-whitelisting (*Falls back to Keyring `grobler_gmail`) |
| `EBOEKHOUDEN_MCP_IMAP_PASSWORD` | No | — | IMAP password or app password for auto-whitelisting (*Falls back to Keyring `grobler_gmail`) |
| `EBOEKHOUDEN_MCP_API_URL` | No | `https://api.e-boekhouden.nl/` | Official e-Boekhouden REST API endpoint |
| `EBOEKHOUDEN_MCP_ALLOW_CUSTOM_API_URL` | No | `false` | Restrict connections strictly to official API host unless set to `true` |
| `EBOEKHOUDEN_MCP_SOURCE` | No | `MCP-Server` | Source identifier logged with API requests |
| `EBOEKHOUDEN_MCP_LOG_LEVEL` | No | `WARNING` | Diagnostics level logged to stderr (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `EBOEKHOUDEN_MCP_ENABLE_ARCHIVE_TOOL` | No | `false` | Enable Microsoft Graph digital archive mailbox delivery |
| `EBOEKHOUDEN_MCP_ARCHIVE_ROOT` | 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:**
```json
{
"mcpServers": {
"eboekhouden": {
"command": "/path/to/eboekhouden-mcp/.venv/bin/eboekhouden-mcp",
"args": []
}
}
}
```
**Windows:**
```json
{
"mcpServers": {
"eboekhouden": {
"command": "C:/path/to/eboekhouden-mcp/.venv/Scripts/eboekhouden-mcp.exe",
"args": []
}
}
}
```
Or via Python module:
```json
{
"mcpServers": {
"eboekhouden": {
"command": "/path/to/eboekhouden-mcp/.venv/bin/python",
"args": ["-m", "eboekhouden_mcp.server"]
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```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:
```json
{
"mcpServers": {
"eboekhouden": {
"command": "python",
"args": ["-m", "eboekhouden_mcp.server"],
"env": {
"EBOEKHOUDEN_MCP_ENABLE_WRITE_TOOLS": "true",
"EBOEKHOUDEN_MCP_REQUIRE_BIOMETRIC": "true"
}
}
}
}
```
### Claude Code
```bash
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`](https://docs.astral.sh/uv/) or standard virtual environments:
```bash
# 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):
```bash
python -c "import keyring; keyring.set_password('eboekhouden_mcp', 'secret_token', 'your-token-here')"
```
Or copy `.env.example` to `.env`:
```bash
cp .env.example .env
# Edit .env and supply your EBOEKHOUDEN_MCP_SECRET_TOKEN
```
### 3. Verify Configuration
```bash
eboekhouden-mcp --check-config
```
### 4. Run the Test Suite
```bash
pytest --cov
```
All 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`](https://github.com/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`](https://github.com/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 22-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`](NOTICE) and [`LICENSE`](LICENSE) files for complete license texts and third-party copyright notices.
---
## License
Released under the **[MIT License](LICENSE)**.