Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@acumulus-mcp create an invoice for Acme BV for €500 in consulting"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for Acumulus — let an AI assistant (Claude Desktop, Claude Code, Cursor, …) read and modify your Acumulus administration through natural language, over the official Acumulus API.
Runs locally over stdio. Your Acumulus credentials stay on your machine; there is no telemetry and no proxy.
pip install acumulus-mcpRequires Python 3.10+.
Related MCP server: Exact Online MCP Server
The server authenticates with your Acumulus contract code, username
and an API token (generate one in Acumulus under your profile; it travels
in the API's <password> field). Provide them as environment variables:
export ACUMULUS_CONTRACT_CODE=123456
export ACUMULUS_USERNAME=your-username
export ACUMULUS_API_TOKEN=your-api-token
# optional: validate writes without persisting them
export ACUMULUS_TESTMODE=1Claude Code:
claude mcp add acumulus \
-e ACUMULUS_CONTRACT_CODE=123456 \
-e ACUMULUS_USERNAME=your-username \
-e ACUMULUS_API_TOKEN=your-api-token \
-- acumulus-mcpClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"acumulus": {
"command": "acumulus-mcp",
"env": {
"ACUMULUS_CONTRACT_CODE": "123456",
"ACUMULUS_USERNAME": "your-username",
"ACUMULUS_API_TOKEN": "your-api-token"
}
}
}
}Restart your client, then try: "Use the acumulus whoami tool to test the connection."
Tool | What it does |
| Sanity-check the connection (lists the account picklist). |
| Fetch reference data: |
| Add an invoice ( |
| Escape hatch — call any Acumulus endpoint directly (e.g. |
The acumulus_request tool means every Acumulus function is reachable even
before it gets a dedicated wrapper — the credential/envelope is added for you;
you only pass the endpoint path and the function-specific fields.
Set ACUMULUS_TESTMODE=1 to have Acumulus validate write calls without
persisting them — do a dry run before pointing it at the live administration.
AGPL-3.0-or-later. For a commercial license, contact nick@easeo.nl.
Call any Acumulus function endpoint directly.
Use this for endpoints not covered by the dedicated tools below.
Args: api_path: Path below the stable base, matching the Acumulus docs, e.g. "picklists/picklist_vattypes.php", "invoices/invoice_add.php", "invoices/invoice_set_payment_status.php", "entry/entry_info.php". fields: Extra fields merged into the request envelope. Nested dicts become nested elements; a list value repeats its element (e.g. {"customer": {"invoice": {"line": [{...}, {...}]}}}). Do NOT include the contract/credentials block — that is added for you.
Returns: JSON-encoded response from Acumulus.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| api_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose real behavioral context: the contract/credentials block is injected automatically (auth handling), fields are merged into the request envelope, nested dicts become nested elements, and list values repeat their element. What it omits is the risk profile — it can reach write endpoints like invoices/invoice_add.php, yet nothing states whether calls are mutating, destructive, or idempotent, which matters for an unrestricted passthrough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the routing rule are front-loaded in the first two lines, with Args/Returns following in a standard order. The four example paths are slightly verbose but each illustrates a different endpoint shape, so they earn their place; there is no filler prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic passthrough tool, the description covers path format, payload construction, credential handling, and that the response is JSON-encoded; an output schema exists so return values need not be detailed. The gap is operational guidance on failure modes (invalid api_path, Acumulus error envelopes) and on which endpoints are safe to call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: api_path is explained with four concrete path examples, and fields is documented with merge semantics, nested-dict-to-element mapping, list repetition, and an explicit exclusion ('Do NOT include the contract/credentials block'). That is meaningfully more than the bare 'Fields'/'Api Path' titles in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Call any Acumulus function endpoint directly') and immediately scopes it against the sibling tools ('endpoints not covered by the dedicated tools below'). An agent can tell this apart from create_invoice, list_picklist, and whoami without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the selecting condition clearly: use this only for endpoints not covered by the dedicated tools. That implicitly names the alternatives (the siblings) but does not spell out when-not to use it (e.g. 'do not use this if a dedicated tool exists for the operation you need'), nor does it warn that writes made through this path bypass the validated dedicated tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an invoice to Acumulus (invoices/invoice_add.php).
Args: customer: Customer-block fields. Common ones: type, contactid, companyname1, fullname, address1, postalcode, city, countrycode, vatnumber, email, overwriteifexists. lines: One dict per invoice line. Common fields: product, itemnumber, unitprice (excl. VAT, 4 decimals), vatrate (defaults to 21), quantity (defaults to 1), nature. invoice: Optional invoice-block fields: concept, number, vattype, issuedate, costcenter, accountnumber, paymentstatus, paymentdate, description, template, invoicenotes.
Set ACUMULUS_TESTMODE=1 to validate without persisting.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | Yes | ||
| invoice | No | ||
| customer | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that this is a mutating 'Add' operation and that ACUMULUS_TESTMODE=1 enables non-persisting validation, but it omits authentication needs, rate limits, and reversibility or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and then structured under 'Args:' with parameter names. It is appropriately sized and each section earns its place, though it could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-object create tool with no annotations, the description covers the action, the main parameter shapes, and a dry-run option. An output schema exists, so return values need no explanation; remaining gaps like auth and sibling selection keep it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it documents common customer fields, line-item fields, defaults like vatrate=21 and quantity=1, unitprice format, and optional invoice-block fields. This adds substantial meaning beyond the empty schema property definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: 'Add an invoice to Acumulus (invoices/invoice_add.php).' It is clearly distinct from generic siblings like whoami, acumulus_request, and list_picklist, even though it does not name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is 'Set ACUMULUS_TESTMODE=1 to validate without persisting,' which is an operational option rather than a when-to-use statement. It does not explain when to prefer this tool over acumulus_request or describe prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List an Acumulus picklist (reference data for dropdowns/validation).
Args: picklist: The picklist name. Common values: "accounts" (bank/ledger accounts), "contacts", "products", "vattypes", "costcenters", "costheadings", "companytypes". The endpoint called is picklists/picklist_.php.
Returns the parsed response plus the extracted item list under items.
| Name | Required | Description | Default |
|---|---|---|---|
| picklist | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It helpfully discloses the concrete endpoint pattern (picklists/picklist_<picklist>.php) and the shape of the return, and 'List' implies read-only, but it says nothing about auth requirements, pagination, caching, or error behavior for unknown picklist names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first line, followed by a tight Args block. The endpoint detail and return note are short and every sentence adds information; nothing is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be fully spelled out, and the description still notes the extracted `items` list. Combined with the enumerated picklist values, an agent has enough to call it correctly, though guidance on unknown picklist names is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% with a single required string parameter, so the description must compensate, and it does: it enumerates the common picklist values ('accounts', 'contacts', 'products', 'vattypes', etc.). It still does not say whether arbitrary values are accepted or what happens on an invalid name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List an Acumulus picklist') and clarifies the domain with 'reference data for dropdowns/validation'. It is clearly distinguishable from create_invoice and whoami, but it never contrasts itself with the generic acumulus_request sibling, which could also reach the same endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the parenthetical about dropdowns/validation. There is no explicit statement of when to reach for this tool versus calling the underlying endpoint via acumulus_request, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sanity-check the Acumulus connection by listing the account picklist.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It discloses that the operation is a read-only listing used as a connectivity check, which is useful context, but it doesn't mention side effects (none expected), authentication requirements, error behavior, or what happens on connection failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It states the purpose and method compactly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no annotations, and existence of an output schema (so return values need not be described), the description is adequate but thin: it could clarify expected output or error conditions for a connectivity check, and it doesn't differentiate from sibling 'list_picklist'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter semantics are not applicable; baseline 4 applies. The description correctly implies no inputs are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: sanity-check the Acumulus connection by listing the account picklist. This clearly tells an agent what the tool does, though the name 'whoami' suggests identity introspection rather than a connection check, and it doesn't explicitly distinguish itself from the sibling 'list_picklist'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'sanity-check the Acumulus connection' implies when to use it (to verify connectivity), but there's no explicit guidance on when to prefer this over 'acumulus_request' or 'list_picklist', nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0acumulus_requestcreate_invoicelist_picklistwhoamiScored across 4 tools
whoami and list_picklist with picklist="accounts" perform essentially the same call, creating genuine redundancy. acumulus_request also overlaps with every dedicated tool by design, though its description explicitly steers usage toward uncovered endpoints, which mitigates the fuzziness.
create_invoice and list_picklist follow a clean verb_noun pattern, but whoami is a bare verb-less word and acumulus_request is a namespaced prefix_noun, so the set mixes three conventions. Still readable but not predictable.
Four tools is on the thin side, but for an API wrapper the generic acumulus_request plus two focused helpers and a connection check is defensible. whoami is arguably redundant given list_picklist, keeping it just shy of ideal.
acumulus_request makes any Acumulus endpoint reachable, so there are no true dead ends. However dedicated coverage is sparse — invoice creation exists but no dedicated get/update/delete invoice or payment-status tools, leaving common lifecycle operations to the generic escape hatch.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
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.
Query your books, company data, business health, and ship invoices from your AI assistant.
Affiliate network reporting in your AI client. Bring your own keys. Most adapters experimental.
