@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: docs/mcp-server.md — complete tool reference with parameters, usage examples, error guide, and multi-client setup.

Requirements

• Node.js 20+
• Kirjapro account with Company or Custom subscription tier
• API key (generate at Settings > API-avaimet)

Quick Start

1. Generate an API Key

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

2. Configure your MCP client

Claude Code

Add to .claude/mcp.json:

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

Claude Desktop

Add to claude_desktop_config.json:

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

3. Verify

In Claude Code, run /mcp to see the available Kirjapro tools.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | KIRJAPRO_API_KEY | Yes* | API key from Settings > API-avaimet |

Legacy (development only)

| Variable | Required | Description | |----------|----------|-------------| | SUPABASE_URL | Yes* | Supabase project URL | | SUPABASE_ACCESS_TOKEN | Yes* | User's JWT access token | | KIRJAPRO_COMPANY_ID | Yes* | Company UUID to operate on |

*Either KIRJAPRO_API_KEY or all three legacy variables must be set.

Tools (28)

Read Tools

| Tool | Description | |------|-------------| | kirjapro_list_accounts | List chart of accounts with filtering by type | | kirjapro_list_transactions | List transactions with journal entries for a fiscal year | | kirjapro_search_transactions | Search transactions by text, date range, or amount | | kirjapro_get_transaction | Get single transaction with journal entries and account details | | kirjapro_list_invoices | List invoices with customer names, filter by status | | kirjapro_get_invoice | Get single invoice with lines, payments, and VAT breakdown | | kirjapro_list_customers | List customers with search | | kirjapro_get_customer | Get single customer with invoice stats | | kirjapro_list_bank_accounts | List active bank accounts with balances | | kirjapro_list_bank_transactions | List bank transactions with filtering | | kirjapro_list_fiscal_years | List fiscal years with open/closed status | | kirjapro_get_dashboard | Financial dashboard: revenue, expenses, invoice stats, bank balances | | kirjapro_get_income_statement | Income statement (tuloslaskelma) for a date range | | kirjapro_get_balance_sheet | Balance sheet (tase) as of a specific date | | kirjapro_get_ar_aging | Accounts receivable aging (0-30, 31-60, 61-90, 90+ days) | | kirjapro_get_general_ledger | General ledger (pääkirja) for one account with running balance |

Write Tools

| Tool | Description | |------|-------------| | kirjapro_create_transaction | Create an accounting transaction with journal entries | | kirjapro_create_transactions_batch | Bulk create up to 50 transactions (partial success) | | kirjapro_create_invoice | Create invoice with auto-generated number and reference | | kirjapro_create_customer | Create customer with Y-tunnus validation | | kirjapro_update_customer | Update customer fields (partial update, re-validates Y-tunnus) | | kirjapro_record_payment | Record payment against an invoice | | kirjapro_update_invoice_status | Update invoice status with state machine validation | | kirjapro_delete_invoice | Delete draft invoices (audit-safe) | | kirjapro_match_bank_transaction | Match bank transaction to an invoice |

Validation Tools

| Tool | Description | |------|-------------| | kirjapro_validate_business_id | Validate Finnish Y-tunnus | | kirjapro_validate_iban | Validate Finnish IBAN | | kirjapro_generate_reference | Generate viitenumero with check digit |

Resources (4)

| URI | Description | |-----|-------------| | kirjapro://accounts/chart | Finnish standard chart of accounts (YSE 2017) | | kirjapro://vat-rates | Finnish VAT rates (25.5%, 13.5%, 10%, 0%) | | kirjapro://company/info | Current company details | | kirjapro://fiscal-years | Fiscal years with open/closed status |

Development

cd mcp-server
npm install
npm run dev     # Run with tsx
npm run build   # Build with esbuild
npm test        # Run vitest
npm run lint    # Type check

Publishing

Releases are automated via GitHub Actions. To publish:

1. Update version in package.json, server.json, and src/index.ts
2. Update CHANGELOG.md
3. Commit and tag: git tag mcp-server/v0.2.0
4. Push: git push origin mcp-server/v0.2.0

The workflow validates version consistency, runs tests, publishes to npm, and creates a GitHub Release.

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 the user's JWT with Row Level Security (RLS)
• Automatic token refresh keeps long-running MCP sessions alive
• Feature gate: requires hasApiAccess (Company/Custom tier)
• Rate limiting: 10 auth requests per minute per key