accountone-mcp

Model Context Protocol server for the AccountOne API.

Lets MCP-capable clients (Claude Desktop, Claude Code, custom agents) read AccountOne business data — account status, payments, orders, monthly bookkeeping reconciliation, and dev flags — over stdio.

Tools

| Tool | Endpoint | Required input | Purpose | | --- | --- | --- | --- | | ao_status | GET /mcp/v1/status | — | Festschreibung (closed payment_matrix and umsatz_matrix), interface health, recent transaction count | | ao_order | GET /mcp/v1/order | source_order_nr | Order line items for a given order number | | ao_payment | GET /mcp/v1/payment | one of matching_source_order_nr, payment_identifier | Payments matched to an order or a payment reference | | ao_order_month_summary | GET /mcp/v1/order_month_summary | jahrmonat (YYYY-MM) | Monthly bookkeeping reconciliation aggregated by VAT, country, marketplace |

All responses are returned as both human-readable JSON text and structured structuredContent validated against the tool's outputSchema.

Configuration

Configured via environment variables in your MCP client config:

| Var | Required | Default | Notes | | --- | --- | --- | --- | | AO_API_TOKEN | yes | — | Bearer token issued by AccountOne. Token shape: <user_id>.<secret>. Generate in the AccountOne UI under "API Tokens". The token must hold the mcp role (or admin) for /mcp/v1/*. |

Install / use

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "accountone": {
      "command": "npx",
      "args": ["-y", "accountone-mcp"],
      "env": {
        "AO_API_TOKEN": "<your-token>"
      }
    }
  }
}

Claude Code

claude mcp add accountone -- npx -y @accountone/mcp

Then set AO_API_TOKEN in the resulting config.

Pointing at staging / dev

{
  "mcpServers": {
    "accountone": {
      "command": "npx",
      "args": ["-y", "accountone-mcp"],
      "env": {
        "AO_API_TOKEN": "<your-dev-token>"
      }
    }
  }
}

Development

npm install
npm run dev            # tsx watch — runs against stdio
npm run build          # emits dist/
npm run typecheck

Quick MCP smoke-test against a live AccountOne backend:

(printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ao_status","arguments":{}}}'; sleep 2) | \
  AO_API_TOKEN=<token> node dist/index.js

Errors

Tool errors bubble up as MCP isError: true results with the AccountOne message, e.g. "Insufficient permissions", "Too Many Requests", "Invalid query parameters". The AccountOne API has a server-wide rate limit of 0.1 req/s per token (one call every ten seconds) — bursts return HTTP 429.

Publish

npm version <patch|minor|major>
npm publish

prepublishOnly runs the TS build. The published tarball ships only dist/, README.md, and LICENSE.

License

Proprietary — Copyright (c) 2026 AccountOne GmbH. All rights reserved. See LICENSE.