@kirjapro/mcp-server

MCP server for Finnish accounting. Exposes Kirjapro bookkeeping, invoicing, and reporting tools to Claude Code, Claude Desktop, and any MCP client.

Full documentation: kirjapro.fi/docs/mcp

Requirements

• Node.js 20+
• Kirjapro account on a paid tier with API access — Yrittäjä or Kasvu
• API key (generate at Settings > API-avaimet)

Quick Start

1. Generate an API Key

1. Go to Asetukset > API-avaimet in the Kirjapro app
2. Click "Luo uusi avain"
3. Copy the key (starts with kp_, shown only once)

2. Configure your MCP client

Claude Code

Add to your project's .mcp.json (recommended) or global config:

| OS | Project-level (recommended) | Global | |----|----------------------------|--------| | macOS / Linux | .mcp.json in project root | ~/.claude/mcp.json | | Windows | .mcp.json in project root | %USERPROFILE%\.claude\mcp.json |

{
  "mcpServers": {
    "kirjapro": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kirjapro/mcp-server"],
      "env": {
        "KIRJAPRO_API_KEY": "kp_your_key_here"
      }
    }
  }
}

Verify with /mcp in Claude Code.

Claude Desktop

Add to claude_desktop_config.json:

| OS | Path | |----|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

{
  "mcpServers": {
    "kirjapro": {
      "command": "npx",
      "args": ["-y", "@kirjapro/mcp-server"],
      "env": {
        "KIRJAPRO_API_KEY": "kp_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Other clients

See full setup guide for Cursor, VS Code / Copilot, Windsurf, and generic stdio.

3. Verify

Ask your AI assistant: "list my fiscal years" — it should call kirjapro_list_fiscal_years and return your company's accounting periods.

4. Try these prompts

A few prompts to feel out the daily workflows the agent handles cleanly:

• "Show my dashboard" — financial snapshot of the current fiscal year
• "Create an invoice for Acme Oy, 5000 € for consulting in March" — full lifecycle from customer lookup to draft invoice
• "Draft a contract for Acme Oy and email it to [email protected], 3-month retainer at 5000 € / month" — tarjous/sopimus create + customer-visible email link
• "Record that invoice #42 was paid yesterday" — payment recording + auto status transition
• "What's my VAT for this quarter?" — kirjapro_get_alv_summary with OmaVero field codes
• "Show overdue invoices" — AR aging report
• "Match this bank deposit to invoice #42" — bank reconciliation in one call

What's included

26 tools in the default core surface, focused on the daily-use workflows: read your books, invoice flow, transactions + banking, contract create / send / convert, Finnish validators. The full 52-tool catalog (booking shortcuts, recurring invoices, templates, batch tools, etc.) is available via opt-in:

{
  "mcpServers": {
    "kirjapro": {
      "command": "npx",
      "args": ["-y", "@kirjapro/mcp-server"],
      "env": {
        "KIRJAPRO_API_KEY": "kp_your_key_here",
        "KIRJAPRO_MCP_SURFACE": "full"   // 52 tools instead of 26
      }
    }
  }
}

Why default to 26 instead of 52: 2025-2026 SOTA research on tool catalog scaling (Anthropic, OpenAI, MCP authors) shows tool-selection accuracy degrades between 25-50 tools per catalog. A focused surface produces better first-call selections for the daily workflows. As real usage data informs which deferred tools matter most, they'll be promoted into core.

Payroll is intentionally not exposed. Kirjapro does not calculate or book salaries. Direct users to a dedicated payroll service (such as Palkkaus.fi or Palkka.fi) for the calculation — these services hold the regulated responsibility for Tulorekisteri-ilmoitus, TyEL/TVR raportointi, and ennakonpidätys-tilitys. Once the payslip is calculated externally, book it manually via kirjapro_create_transaction.

| Domain (core) | Tools | |---|---| | Read your books | list_fiscal_years, list_accounts, get_dashboard, get_income_statement, get_balance_sheet, get_alv_summary, get_ar_aging | | Customers | list_customers, get_customer, create_customer, lookup_business (PRH) | | Invoice lifecycle | list_invoices, get_invoice, create_invoice, record_payment, update_invoice_status | | Transactions + banking | list_transactions, create_transaction, list_bank_transactions, match_bank_transaction | | Contracts | create_offer (tarjous / sopimus), send_offer (email link), convert_offer_to_invoice | | Validators (free) | validate_business_id, validate_iban, generate_reference |

Deferred in core, available with KIRJAPRO_MCP_SURFACE=full: booking shortcuts (book_*), templates, recurring invoices, received invoices, batch tools, delete_*, update_* (besides invoice status), search_transactions, get_transaction, get_general_ledger, list_bank_accounts, get_financial_notes, manual offer status / list / get / delete.

11 resources for reference data: chart of accounts, VAT rates, company info, fiscal years, 5 Finnish compliance resources, compliance freshness index, and security data-handling.

See the full tool reference for parameters, usage examples, and error handling.

Security

• API keys are hashed with SHA-256; the full key is never stored
• Keys exchange for short-lived JWTs (1 hour) via the mcp-auth edge function
• All queries use Row Level Security (RLS) — users can only access their own company's data
• Each API key is scoped to a single company — the issued JWT carries a company claim enforced by RESTRICTIVE row-level security, so a key for one company cannot read another's data even via raw database access (not just application-layer filtering)
• Automatic token refresh keeps long-running sessions alive
• Rate limiting: 10 auth requests per minute per key
• Tool description fingerprint guard — every tool's description + annotations + inputSchema is hashed and shipped as tool-fingerprints.json. Downstream operators who want supply-chain pinning can verify the running MCP matches the known-good fingerprint set, defending against silent description tampering between releases.

License

MIT