Salaxy

A Model Context Protocol server that exposes a Finnish payroll (palkanlaskenta) API as MCP tools. Built with the official TypeScript MCP SDK.

Tools

get_income_types

Returns all Finnish payroll income types (tulolajit) supported by the server.

Parameters: none

Returns: JSON array of income types, each with:

Field	Description
code	Incomes Register (tulorekisteri) code, e.g. "101"
name_fi	Finnish name, e.g. "Aikapalkka"
name_en	English translation, e.g. "Time-based wage"
indicative_tax_rate_pct	Flat withholding rate used in demo calculations
description	Plain-language description of the income type

Supported codes include time-based wages (101), piece-rate wages (102), overtime (201), shift supplements (210), holiday compensation (301), holiday bonus (302), sick pay (401), fringe benefits (501, 502), and commission pay (601).

---

calculate_salary

Calculates gross and net salary by applying Finnish statutory deductions:

• Income tax — based on the income type's indicative withholding rate
• TyEL pension — 7.45 % employee contribution (2024 rate)
• Unemployment insurance — 0.79 % employee share (2024 rate)

Parameters:

Parameter	Type	Description
base_salary	number	Hourly rate (€) when hours_worked > 0; monthly salary (€) when hours_worked = 0
income_type_code	string	Income type code from get_income_types, e.g. "101"
hours_worked	number	Hours in the pay period; pass 0 for a fixed monthly salary

Returns:

{
  "income_type": { "code": "101", "name_fi": "Aikapalkka", "name_en": "Time-based wage" },
  "currency": "EUR",
  "deduction_rates": {
    "income_tax_pct": 25,
    "pension_pct": 7.45,
    "unemployment_pct": 0.79
  },
  "gross_salary": 3080.00,
  "income_tax": 750.03,
  "pension_deduction": 229.46,
  "unemployment_deduction": 24.33,
  "net_salary": 2076.18,
  "hours_worked": 80,
  "effective_hourly_rate": 38.50
}

---

get_employee

Returns mock employee master data by ID.

Parameters:

Parameter	Type	Description
employee_id	string	Employee identifier (case-insensitive). Available: EMP001, EMP002, EMP003, EMP004

Returns:

{
  "employee": {
    "id": "EMP001",
    "first_name": "Mikael",
    "last_name": "Virtanen",
    "ssn_masked": "150385-****",
    "employment_type": "Toistaiseksi voimassa oleva / Permanent",
    "department": "Ohjelmistokehitys / Software Development",
    "hourly_rate": 38.5,
    "monthly_salary": 6160,
    "tax_card_rate": 28,
    "municipality": "Helsinki",
    "iban": "FI21 1234 5600 0007 85"
  }
}

---

Getting started

npm install
npm run build
npm start

The server communicates over stdio (standard MCP transport). To integrate with Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "salaxy": {
      "command": "node",
      "args": ["/absolute/path/to/salaxy-mcp/dist/index.js"]
    }
  }
}

Project structure

salaxy-mcp/
├── src/
│   ├── index.ts   # MCP server, tool definitions, salary calculation logic
│   └── data.ts    # Income types and mock employee data
├── package.json
├── tsconfig.json
└── README.md

Notes

• Tax rates and statutory deduction percentages are illustrative 2024 values for demonstration purposes and should not be used for real payroll.
• SSNs in mock data are masked; IBANs are synthetic.