npm package: @kirjapro/mcp-server
Description: MCP server for Finnish accounting — exposes Kirjapro bookkeeping, invoicing, and reporting tools to Claude Code, Claude Desktop, and any MCP client.
Latest version: 0.5.0

# @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](../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`:

```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`:

```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 (40)

### 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 |
| `kirjapro_list_templates` | List transaction templates for common bookkeeping patterns |
| `kirjapro_list_offers` | List offers/contracts with customer names |
| `kirjapro_get_offer` | Get offer detail with lines, events, and VAT breakdown |

### 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 |
| `kirjapro_create_from_template` | Create transaction from template with VAT splitting |
| `kirjapro_create_from_template_batch` | Bulk create from templates (up to 50) |
| `kirjapro_book_sale` | Book a sale with automatic VAT splitting (invoice/cash/prepaid) |
| `kirjapro_book_purchase` | Book a purchase with VAT, reverse charge, or edustus |
| `kirjapro_book_salary` | Book salary with 2026 Finnish social insurance rates |
| `kirjapro_book_vat_settlement` | Book ALV-tilitys from journal entries |
| `kirjapro_create_offer` | Create offer/contract with auto-generated number |
| `kirjapro_update_offer_status` | Update offer status with state machine validation |
| `kirjapro_delete_offer` | Delete draft offers/contracts |

### 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

```bash
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.3.0`
4. Push: `git push origin mcp-server/v0.3.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