CalcBloc tax and salary calculator

CalcBloc MCP server: take-home pay, employer cost and official tax tables for AI assistants

calcbloc-mcp is a Model Context Protocol (MCP) server that lets AI assistants work out take-home pay, employer cost and cross-country salary comparisons, and look up official income tax and social security tables, using CalcBloc data. It covers 37 countries, including the United States (all states), the United Kingdom, Canada, Australia, India, Germany, France, Spain and the Netherlands. Every answer states the tax year, links the official government sources behind the rates, and carries the credit "Data by CalcBloc".

CalcBloc is a product of itmarkerz technologies.

Install with npx -y calcbloc-mcp (npm package). The server is listed in the official MCP Registry as io.github.itmarkerz/calcbloc-mcp.

Contents

• What it does
• Quick start
• Set up your AI client
• Tools
• Sample calls
• Configuration
• Limits and caching
• Offline tax tables
• Development
• Data, licence and credit

What it does

Ask your assistant things like:

• "What is my take-home pay on $85,000 in California, filing single?"
• "How much does it cost a German employer to hire someone on €60,000?"
• "Compare £50,000 in Scotland with the same salary in Germany."
• "Show me the 2026 Ontario income tax brackets and where they come from."
• "What are the UK National Insurance thresholds for 2026-27?"

The server provides five read-only tools:

Calculations run on CalcBloc's public API (calcbloc.com/developers), the same engines and data as the calculators on calcbloc.com. Every result includes:

• the tax year the figures apply to;
• the official source URLs (government or statutory publications) for the rates used, with the date each was last checked;
• the calcbloc.com page for the result (calculator or tax-table page);
• the credit "Data by CalcBloc" and a short note that the figures are an estimate, not tax advice.

Tax tables are available for all 37 countries. Take-home pay calculations currently cover 12 of them (US, UK, Canada, Australia, New Zealand, Ireland, India, Germany, France, Spain, the Netherlands and Singapore); for the others the tools say so and link the country's tax tables. list_countries always shows the live list.

Quick start

Requirements: Node.js 20 or newer.

npx -y calcbloc-mcp

The server talks MCP over stdio, so you normally do not run it yourself: you add it to your AI client with the snippets below, and the client starts it when needed. No API key is required. A free key raises the daily limit (see Limits and caching).

Set up your AI client

All clients use the same command, npx -y calcbloc-mcp. The CALCBLOC_API_KEY entry is optional: leave it out, or paste your free key from calcbloc.com/developers/keys.

Claude Desktop

Open Settings > Developer > Edit Config and add the server to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\, Linux: ~/.config/Claude/):

{

"mcpServers": { "calcbloc": { "command": "npx", "args": ["-y", "calcbloc-mcp"], "env": { "CALCBLOC_API_KEY": "your-free-key" } } } }

Quit and restart Claude Desktop.

Claude Code

claude mcp add --transport stdio calcbloc -- npx -y calcbloc-mcp

With an API key, available in all your projects:

claude mcp add --transport stdio --scope user --env CALCBLOC_API_KEY=your-free-key calcbloc -- npx -y calcbloc-mcp

To share it with a project, add it to .mcp.json at the project root and keep the key in your environment:

{

"mcpServers": { "calcbloc": { "command": "npx", "args": ["-y", "calcbloc-mcp"], "env": { "CALCBLOC_API_KEY": "${CALCBLOC_API_KEY:-}" } } } }

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{

"mcpServers": { "calcbloc": { "command": "npx", "args": ["-y", "calcbloc-mcp"], "env": { "CALCBLOC_API_KEY": "your-free-key" } } } }

VS Code (GitHub Copilot)

Add to .vscode/mcp.json, or run MCP: Add Server from the Command Palette. VS Code asks for the key the first time and stores it securely:

{

"inputs": [ { "type": "promptString", "id": "calcbloc-api-key", "description": "CalcBloc API key (optional, leave empty for anonymous use)", "password": true } ], "servers": { "calcbloc": { "type": "stdio", "command": "npx", "args": ["-y", "calcbloc-mcp"], "env": { "CALCBLOC_API_KEY": "${input:calcbloc-api-key}" } } } }

Or from a terminal, without a key:

code --add-mcp '{"name":"calcbloc","type":"stdio","command":"npx","args":["-y","calcbloc-mcp"]}'

Windsurf and Devin

Devin Desktop and Devin CLI read ~/.config/devin/mcp_config.json (Windows: %APPDATA%\devin\mcp_config.json) or .devin/mcp_config.json in a project. Windsurf uses the same mcpServers format in its MCP settings (raw config):

{

"mcpServers": { "calcbloc": { "command": "npx", "args": ["-y", "calcbloc-mcp"], "env": { "CALCBLOC_API_KEY": "your-free-key" } } } }

OpenAI Codex (CLI, IDE extension and app)

codex mcp add calcbloc -- npx -y calcbloc-mcp

or in ~/.codex/config.toml:

[mcp_servers.calcbloc]

command = "npx" args = ["-y", "calcbloc-mcp"]

[mcp_servers.calcbloc.env] CALCBLOC_API_KEY = "your-free-key"

Other MCP clients

Any client that can start a local (stdio) MCP server works: use the command npx with the arguments -y calcbloc-mcp, and optionally set CALCBLOC_API_KEY in its environment.

Tools

All tools are read-only and idempotent, and declare an output schema; results come back as readable text plus structuredContent that matches the schema.

calculate_take_home_pay

Returns net annual pay, total deductions and effective rate where available, the engine's full results, a yearly/monthly/weekly breakdown, notes and the inputs used.

calculate_employer_cost

Same arguments as calculate_take_home_pay (with employer options such as UK pension_mode or US health_per_month). Returns the total yearly and monthly cost, the cost multiplier where available, and a breakdown of employer contributions.

compare_countries

Returns both sides (gross, income tax, contributions, take-home pay, effective rate, assumptions), the exchange rate and date, the difference, and a plain-English summary.

get_tax_tables

Returns each section's rows (bands with from/to/rate, or values with units), its basis, notes and official source, plus links to the tax-table page, the JSON API and a CSV download. Very long tables return a section index first, so the assistant can ask for the part it needs.

list_countries

Without arguments, lists every country with its current tax year and which tools work for it. With country, also lists its regions and every calculation option, with allowed values and defaults.

Sample calls

These are real responses from the server (recorded with the MCP SDK client over stdio; the figures come from the CalcBloc API on 11 November 2026). Long source lists are shortened.

Take-home pay, £50,000 in Scotland

{ "name": "calculate_take_home_pay", "arguments": { "country": "uk", "gross_salary": 50000, "region": "scotland" } }

Take-home pay in United Kingdom (Scotland), tax year 2026-27

Gross salary: GBP 50,000.00 (annual gross salary in GBP) Take-home pay: GBP 38,024.07 a year Effective deduction rate: 23.95%

Your pay in 2026/27 (Year | Month | Week, GBP):

• Gross salary: 50,000.00 | 4,166.67 | 961.54
• Income Tax: 8,982.05 | 748.50 | 172.73
• National Insurance: 2,993.88 | 249.49 | 57.57
• Take-home pay: 38,024.07 | 3,168.67 | 731.23

... Calculator: https://calcbloc.com/uk/take-home-pay-calculator Tax tables: https://calcbloc.com/uk/tax-tables/2026-27/scotland

Official sources:

• HMRC: Income Tax rates and allowances for current and previous tax years (updated 6 April 2026): https://www.gov.uk/government/publications/rates-and-allowances-income-tax/income-tax-rates-and-allowances-current-and-past (checked 2026-10-16)
• GOV.UK: Rates and thresholds for employers 2026 to 2027 (Class 1 National Insurance thresholds and rates): https://www.gov.uk/guidance/rates-and-thresh