accounting-mcp

Multi-tenant remote MCP server that connects accounting software to MCP clients (Claude, ChatGPT, Perplexity, Claude Code). Business administrators sign in, connect their accounting company via OAuth, and their AI assistant can then work with their bookkeeping through ~87 tools.

Providers: Bokio (Swedish accounting SaaS). The core is provider-generic — adding Fortnox/Visma later means new files under src/providers + tool definitions, no changes to auth/transport/storage.

Architecture

pnpm/Turborepo monorepo with two deployable apps:

• apps/api — the MCP + auth + billing server (Hono on @hono/node-server).

• apps/web — the user-facing dashboard (Next.js App Router). Talks to the api via tRPC (/trpc, router in apps/api/src/trpc/router.ts, type-only import in the web app) and proxies /api/*, /connect/* and /trpc/* to the api via Next rewrites, so the better-auth session cookie stays first-party on the web origin. The api's WEB_URL env points browser-facing redirects (sign-in, consent, Bokio OAuth callback) at the web origin. See DEPLOY.md.

The api is one stateful Node process with three faces:

1. OAuth 2.1 authorization server toward MCP clients — better-auth + @better-auth/oauth-provider: dynamic client registration, PKCE, sign-in/consent pages, token issuance. Metadata at /.well-known/oauth-authorization-server.

2. MCP resource server at /mcp (Streamable HTTP via @hono/mcp) — validates our JWTs, one session per Mcp-Session-Id, serves the tool set.

3. OAuth client toward Bokio — /connect/bokio flow; company tokens AES-256-GCM-encrypted in Postgres, auto-refreshed with rotation + per-connection mutex.

Users authenticate with email/password; each user can connect multiple Bokio companies. Tools take an optional companyId (defaults when exactly one company is connected); tenant isolation is enforced in src/tools/company-resolver.ts.

Related MCP server: FreeAgent MCP Server

Development

docker compose up -d               # Postgres on localhost:5433
cp apps/api/.env.example apps/api/.env   # fill BETTER_AUTH_SECRET + TOKEN_ENCRYPTION_KEY (openssl rand -base64 32)
pnpm install
pnpm --filter @acc/api db:migrate
pnpm --filter @acc/api dev         # api on http://localhost:3000
pnpm --filter @acc/web dev         # dashboard on http://localhost:3001 (optional; api serves MCP alone)

With BOKIO_MOCK=true (the default in .env.example) a mock Bokio — OAuth endpoints + fixture companies with invoices, journal entries, chart of accounts, SIE export — is mounted at /mock/bokio/v1. The entire product works end-to-end with zero Bokio credentials.

Verify

pnpm turbo run build typecheck test   # all workspaces
pnpm --filter @acc/api e2e            # against a running api: token connect suite + full
                                      # DCR → OAuth → consent → MCP session → tools → SIE flow

Connect from Claude Code: claude mcp add --transport http accounting http://localhost:3000/mcp (the OAuth flow opens in your browser — sign up, approve, then connect a mock company from /dashboard).

Configuration

See .env.example. Highlights:

• BOKIO_ALLOW_WRITES (default false) — when off, mutating tools are not even listed. Write tools carry MCP destructiveHint/readOnlyHint annotations either way.

• BOKIO_MOCK — mock Bokio instead of api.bokio.se.

• TOKEN_ENCRYPTION_KEY — base64 32-byte AES key for provider tokens at rest.

• BOKIO_SCOPES — defaults to every scope documented in the spec (invoices:read, journal-entries:write, …).

Going live with real Bokio

1. Create a developer account + integration at the Bokio developer portal; register redirect URI https://<host>/connect/bokio/callback.

2. Set BOKIO_CLIENT_ID/BOKIO_CLIENT_SECRET, BOKIO_MOCK=false, BASE_URL=https://<host>.

3. For local testing against real Bokio, tunnel with cloudflared tunnel --url http://localhost:3000 and use the tunnel URL as BASE_URL.

Deployment (Railway or any container host)

Multi-stage Dockerfile; the image is self-contained. On Railway: add a Postgres service, set the env vars, use npm run db:migrate as release command, health check GET /healthz. Note: MCP sessions are in-memory — run a single instance (or add sticky sessions before scaling out).

Layout

src/
  auth/       better-auth config (OAuth AS) + Bokio connect flow
  http/       Hono app, /mcp session handling, HTML pages (sign-in/consent/dashboard)
  bokio/      generated OpenAPI types, API client (401-retry), token-manager, mock server
  tools/      declarative registry, meta tools, per-resource Bokio tool tables
  db/         Drizzle schema (better-auth tables + accounting_connection + tool_audit_log)
  lib/        AES-256-GCM token crypto
specs/        Bokio OpenAPI specs (source for npm run gen:bokio)
scripts/      e2e-oauth.mjs — full-flow integration test