CalcBloc tax and salary calculator

CalcBloc MCP 服务：为 AI 助手计算实发工资、雇主成本并查询官方税表

calcbloc-mcp 是一个 Model Context Protocol（MCP）服务，可让 AI 助手使用 CalcBloc 数据计算实发工资、雇主成本及跨国薪资对比，并查询官方所得税和社会保障税表。它覆盖 41 个国家和地区，包括美国（所有州）、英国、加拿大、澳大利亚、印度、德国、法国、西班牙和荷兰。每个回答都会注明纳税年度，附上税率所依据的官方政府来源链接，并标注“Data by CalcBloc”。

CalcBloc 是 itmarkerz technologies 的产品。

使用 npx -y calcbloc-mcp 安装（npm package）。该服务已列入官方 MCP Registry，名称为 io.github.itmarkerz/calcbloc-mcp。

目录

• 功能介绍
• 快速开始
• 设置 AI 客户端
• 工具
• 调用示例
• 配置
• 限制与缓存
• 离线税表
• 开发
• 数据、许可与致谢

功能介绍

可以向助手提出以下问题：

• “在加利福尼亚州以单身身份申报，年薪 85,000 美元时，我的实发工资是多少？”
• “德国雇主聘用一名年薪 60,000 欧元的员工，成本是多少？”
• “比较苏格兰和德国的 50,000 英镑年薪。”
• “请显示安大略省 2026 年的所得税级距，并说明数据来源。”
• “2026-27 年英国国民保险的缴费门槛是什么？”

该服务提供五种只读工具：

工具	返回内容
calculate_take_home_pay	扣除所得税和员工缴费后的净工资，并按年、月和周列出明细
calculate_employer_cost	薪资加雇主社会保障缴费、工资税及其他相关成本
compare_countries	按欧洲央行参考汇率换算并比较两个国家的相同薪资
get_tax_tables	指定国家、年份和地区的官方税表（税率级距、免税额、缴费率和门槛）
list_countries	支持的国家、纳税年度、地区，以及各项计算可用的选项

计算由 CalcBloc 公共 API（calcbloc.com/developers）执行，使用的引擎和数据与 calcbloc.com 上的计算器相同。每项结果均包含：

• 适用的纳税年度；
• 所用税率的官方来源网址（政府或法定出版物），以及每项来源最近核查的日期；
• 结果对应的 calcbloc.com 页面（计算器或税表页面）；
• “Data by CalcBloc” 致谢，以及说明相关数值仅为估算结果、不构成税务建议的简短提示。

所有 41 个国家和地区均提供税表。目前有 12 个国家和地区支持实发工资计算（美国、英国、加拿大、澳大利亚、新西兰、爱尔兰、印度、德国、法国、西班牙、荷兰和新加坡）；对于其他国家和地区，工具会说明情况并链接到相应税表。list_countries 始终显示实时列表。

快速开始

要求：Node.js 20 或更高版本（Node.js）。

npx -y calcbloc-mcp

该服务通过 stdio 使用 MCP，因此通常无需手动运行：只需使用下方的代码片段将其添加到 AI 客户端，客户端会在需要时启动它。无需 API 密钥。免费密钥可提高每日限额（请参阅限额与缓存）。

远程服务（无需安装）

这五个工具也托管在 https://calcbloc.com/mcp（Streamable HTTP，无需登录）。可在通过 URL 连接 MCP 服务的客户端中使用，例如 claude.ai 或 Claude Desktop 的自定义连接器（Settings > Connectors > Add custom connector），也可在 Claude Code 中使用：

claude mcp add --transport http calcbloc https://calcbloc.com/mcp

不使用密钥时，每个地址每天可调用工具 API 500 次（每分钟 30 次），且计入共享的每日总量。若要使用自己的免费密钥（每天 5,000 次），请将其作为 X-API-Key 标头发送，例如 claude mcp add --transport http calcbloc https://calcbloc.com/mcp --header "X-API-Key: your-free-key"，或作为 Authorization: Bearer your-free-key 发送。

设置 AI 客户端

所有客户端使用相同的命令 npx -y calcbloc-mcp。CALCBLOC_API_KEY 项为可选项：可以省略，也可以粘贴从 calcbloc.com/developers/keys 获取的免费密钥。

Claude Desktop

打开 Settings > Developer > Edit Config，并将服务添加到 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"
      }
    }
  }
}

退出并重启 Claude Desktop。

Claude Code

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

使用 API 密钥时，可在所有项目中使用：

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

若要在项目中共享，请将其添加到项目根目录下的 .mcp.json，并将密钥保存在环境变量中：

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

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

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

VS Code（GitHub Copilot）

添加到 .vscode/mcp.json，或从命令面板运行 MCP: Add Server。VS Code 会在首次使用时询问密钥，并安全地保存：

{
  "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}" }
    }
  }
}

也可以在终端中运行（无需密钥）：

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

Windsurf 和 Devin

Devin Desktop 和 Devin CLI 会读取 ~/.config/devin/mcp_config.json（Windows：%APPDATA%\devin\mcp_config.json）或项目中的 .devin/mcp_config.json。Windsurf 在其 MCP 设置中使用相同的 mcpServers 格式（原始配置）：

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

OpenAI Codex（CLI、IDE 扩展和应用）

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

或在 ~/.codex/config.toml 中配置：

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

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

其他 MCP 客户端

任何能够启动本地（stdio）MCP 服务的客户端都适用：使用命令 npx，并传入参数 -y calcbloc-mcp；也可选择在其环境中设置 CALCBLOC_API_KEY。

工具

所有工具均为只读且幂等，并声明了输出架构；结果会以易读文本和符合该架构的 structuredContent 返回。

calculate_take_home_pay

参数	类型	说明
country	字符串，必填	代码或名称：us、uk、canada、india、germany、“United Kingdom”……
gross_salary	数字，必填	以所在国家/地区货币表示的税前薪资。除新加坡外，均为年薪（新加坡为月薪）。
region	字符串	计算因地区而异时使用：美国州（ca）、英国构成国（scotland）、加拿大省（on）、西班牙自治区（md）、德国州（by）、印度州（mh）。
year	字符串	默认使用当前纳税年度（2026 或 2026-27）。较早年度可作为税表使用。
options	对象	国家/地区特定选项，例如美国 {"filing_status": "married", "children": 2}、英国 {"pension_pct": 5, "student_loan": "plan2"}、德国 {"tax_class": 3, "church": true}。list_countries 会列出所有选项。

返回可用时的净年薪、扣款总额和实际税率、引擎的完整结果、按年/月/周划分的明细、备注以及所用的输入值。

calculate_employer_cost

参数与 calculate_take_home_pay 相同（包括英国的 pension_mode 或美国的 health_per_month 等雇主选项）。返回年度和月度总成本、适用时的成本倍数，以及雇主缴款明细。

compare_countries

参数	类型	说明
country_a, country_b	字符串，必填	两个不同的国家，用于计算。
gross_salary	数字，必填	以 currency 表示的年度税前工资。
currency	字符串	国家 A 或国家 B 的货币（ISO 代码）。默认为国家 A 的货币。
region_a, region_b	字符串	美国、英国、加拿大或印度的地区。

返回两侧的结果（税前工资、所得税、缴款、税后收入、有效税率、假设）、汇率和日期、差额，以及通俗易懂的摘要。

get_tax_tables

参数	类型	说明
country	字符串，必填	41 个国家中的任意一个。
year	字符串	默认为最新年份。部分国家还提供上一年数据（例如英国 2025-26）。
region	字符串	地区税表：美国州、加拿大省、英国构成国（苏格兰、威尔士）、瑞士州、西班牙自治区、意大利大区等。
group	字符串	仅限 income-tax、employee、employer 或 other 部分。
sections	字符串[]	仅包含这些部分 ID。

返回每个部分的行（含起止值和税率的档位，或附带单位的数值）、计税依据、备注和官方来源，以及税表页面、JSON API 和 CSV 下载的链接。对于非常长的税表，会先返回部分索引，以便助手询问所需的部分。

list_countries

不带参数时，列出所有国家、当前纳税年度，以及适用于各国的工具。传入 country 时，还会列出该国的地区和所有计算选项，包括允许的取值和默认值。

示例调用

以下是服务端的真实响应（通过 MCP SDK 客户端使用 stdio 记录；数据来自 2026 年 11 月 11 日的 CalcBloc API）。较长的来源列表已缩短。

苏格兰，£50,000 的税后收入

{ "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-thresholds-for-employers-2026-to-2027 (checked 2026-10-16)
...

Estimate for information only, not tax, legal or financial advice. Figures follow the official sources listed; check them, or ask a qualified adviser, before making decisions.
Data by CalcBloc: https://calcbloc.com/uk/take-home-pay-calculator (licence CC BY 4.0, https://calcbloc.com/data)

对应的 structuredContent（已缩短）：

{
  "country": "uk",
  "countryName": "United Kingdom",
  "region": "scotland",
  "taxYear": "2026-27",
  "currency": "GBP",
  "grossSalary": 50000,
  "netAnnual": 38024.07,
  "effectiveRate": 0.2395186,
  "results": { "netMonthly": 3168.6725, "incomeTax": 8982.05, "employeeNi": 2993.88, "employerNi": 6749.4 },
  "taxTablesUrl": "https://calcbloc.com/uk/tax-tables/2026-27/scotland",
  "sources": [{ "title": "HMRC: Income Tax rates and allowances ...", "url": "https://www.gov.uk/government/publications/rates-and-allowances-income-tax/income-tax-rates-and-allowances-current-and-past", "retrievedAt": "2026-10-16" }],
  "calcblocUrl": "https://calcbloc.com/uk/take-home-pay-calculator",
  "attribution": "Data by CalcBloc",
  "licence": "CC BY 4.0",
  "disclaimer": "Estimate for information only, not tax, legal or financial advice. ..."
}

德国，€60,000 的雇主成本

{ "name": "calculate_employer_cost", "arguments": { "country": "germany", "gross_salary": 60000 } }

Employer cost in Germany, tax year 2026
Gross salary: EUR 60,000.00 (annual gross salary in EUR (above the Midijob range))
Total cost to the employer: EUR 73,392.00 a year
Monthly cost: EUR 6,116.00

Employer cost of a €60,000 salary (Berlin) (Year | Month, EUR):
- Gross salary: 60,000.00 | 5,000.00
- Pension insurance (employer half): 5,580.00 | 465.00
- Unemployment insurance (employer half): 780.00 | 65.00
- Health insurance (employer half): 5,250.00 | 437.50
- Long-term care insurance (employer half): 1,080.00 | 90.00
- U1 sick-pay levy (0.8%): 480.00 | 40.00
- U2 maternity levy (0.22%): 132.00 | 11.00
- U3 insolvency levy (0.15%): 90.00 | 7.50
- Total employer cost: 73,392.00 | 6,116.00
...
Data by CalcBloc: https://calcbloc.com/germany/germany-employer-cost-calculator (licence CC BY 4.0, https://calcbloc.com/data)

比较英国和德国，工资为 £50,000

{ "name": "compare_countries", "arguments": { "country_a": "uk", "country_b": "germany", "gross_salary": 50000 } }

Salary comparison: United Kingdom vs Germany, GBP 50,000.00 a year

England, United Kingdom (tax year 2026-27):
- Gross: GBP 50,000.00
- Income Tax: GBP 7,486.00
- National Insurance: GBP 2,993.88
- Take-home pay: GBP 39,520.12 (20.96% deducted)
...
Germany (tax year 2026):
- Gross: EUR 59,941.26
- Wage tax: EUR 9,372.00
...
- Take-home pay: EUR 37,532.10 (37.39% deducted)
...
Exchange rate: 1 GBP = 1.1988 EUR, rates as of 6 November 2026 (European Central Bank reference rates)
Comparison page: https://calcbloc.com/compare/salary

安大略省所得税表

{ "name": "get_tax_tables", "arguments": { "country": "canada", "region": "on", "group": "income-tax" } }

Tax tables: Canada, Ontario, tax year 2026 (in force 2026-01-01 to 2026-12-31)
Currency: CAD. Status: verified.

### Ontario income tax brackets
(section: provincial-income-tax; group: income-tax; basis: Taxable income, per year)
- 0 to 53,891 at 5.05%
- 53,891 to 107,785 at 9.15%
- 107,785 to 150,000 at 11.16%
- 150,000 to 220,000 at 12.16%
- 220,000 and above at 13.16%
Source: T4127 Payroll Deductions Formulas, 122nd Edition, effective January 1, 2026 (CRA), ..., https://www.canada.ca/content/dam/cra-arc/formspubs/pub/t4127-jan/t4127-01-26e.pdf (checked 2026-10-25)
...

尚未提供计算数据的国家

{ "name": "calculate_take_home_pay", "arguments": { "country": "austria", "gross_salary": 50000 } }

Take-home pay calculation is not available for Austria yet. Its official 2026 tax tables are available: call get_tax_tables with country "austria", or see https://calcbloc.com/austria/tax-tables/2026.

配置

所有设置均为可选环境变量，在客户端的 env 块中设置：

变量	默认值	用途
CALCBLOC_API_KEY	无	可选；每日请求超过 50 次后需要。可从 calcbloc.com/developers/keys 免费获取 API 密钥，每次请求都会在 X-API-Key 标头中发送（每日 5,000 次请求，每分钟 60 次）。
CALCBLOC_DATA_DIR	无	包含 CalcBloc 税表数据副本的文件夹。优先从此处读取税表（见离线税表）。
CALCBLOC_API_URL	https://calcbloc.com/api/v1	API 基础 URL（用于测试）。
CALCBLOC_TIMEOUT_MS	20000	请求超时时间，单位为毫秒。
CLAUDE_PLUGIN_OPTION_CALCBLOC_API_KEY	无	使用 CalcBloc Claude 插件传递 API 密钥时采用的同一密钥名称（plugin/）。如果两者都已设置，则优先使用 CALCBLOC_API_KEY。空值和未填写的占位符（例如 ${user_config.calcbloc_api_key}）均视为未设置密钥。

限额与缓存

CalcBloc API 免费使用。不使用密钥时，每个 IP 地址每天可发送 50 次请求，每分钟可发送 5 次；免费密钥每天可发送 5,000 次请求，每分钟可发送 60 次。当不使用密钥的免费额度用尽时（API 返回 429，或报告 X-RateLimit-Remaining: 0），工具错误会提示不使用密钥的免费额度已用完，并继续显示 “添加免费 API 密钥”：其中链接到 calcbloc.com/developers/keys，并说明要在此服务的 env 块中将其设为 CALCBLOC_API_KEY，然后重启。在限额重置之前，服务不会再发送请求（每次工具调用都会立即返回相同的消息）；CALCBLOC_DATA_DIR 中的离线税务表仍可使用。使用密钥时，限额消息会显示该密钥的限额以及何时可以重试。

为节省请求次数，服务会将国家列表和税务表缓存在内存中，缓存有效期为六小时。首次计算某个国家时最多会发送四次请求（国家列表、计算，以及提供官方来源链接的国家级和地区级税务表）；之后计算同一国家时只需发送一次。查询税务表时，每张表会发送一次请求；如果设置了本地数据文件夹，则无需发送请求。

离线税务表

税务表也以开放数据形式（JSON 和 CSV）发布在 calcbloc.com/data。如果你保存了副本，可将 CALCBLOC_DATA_DIR 指向该副本（可以是仓库根目录，也可以是包含 manifest.json 的 tables 文件夹）。随后，get_tax_tables 会直接从文件夹读取数据，不使用 API；即使无法连接 API，也能继续运行。计算始终需要 API。

数据不会打包进 npm 软件包：数据约有 10 MB，而且政府发布变更时会更新税务表，因此打包的副本在版本发布之间可能会过时。

开发

git clone https://github.com/itmarkerz/calcbloc-mcp.git
cd calcbloc-mcp
npm install
npm run build
npm test

• npm test 会构建服务并运行单元测试（模拟 HTTP），以及端到端测试。端到端测试会使用 MCP SDK 客户端，通过 stdio 启动 dist/index.js，并连接到本地 API 模拟服务。

• npm run inspector 会在构建好的服务上启动 MCP Inspector。在命令行中运行：

  npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
  npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/call --tool-name list_countries --tool-arg country=uk
  

• 要在客户端中使用本地构建版本，请将 npx -y calcbloc-mcp 替换为 node /path/to/calcbloc-mcp/dist/index.js。

使用官方 MCP TypeScript SDK v2（@modelcontextprotocol/server 2.4）构建，该 SDK 实现了 2026-07-28 MCP 规范。需要 Node.js 20 或更新版本。

数据、许可与鸣谢

• 税务数据：CalcBloc，采用 CC BY 4.0 许可。鸣谢：“数据来自 CalcBloc (calcbloc.com/data)”。每项数据均取自其旁边注明的官方来源，并标注了最后核验日期。
• 代码：MIT 许可，详见 LICENSE。
• 结果仅供参考，属于估算值，不构成税务、法律或财务建议。

链接

• 网站：calcbloc.com
• API 文档：calcbloc.com/developers
• 免费 API 密钥：calcbloc.com/developers/keys
• 税务表与下载：calcbloc.com/data
• 问题反馈：github.com/itmarkerz/calcbloc-mcp/issues

关于

CalcBloc 由位于印度喀拉拉邦的 Web 和移动应用开发公司 itmarkerz technologies 构建并维护。此服务所用的数据位于 calcbloc.com/data，API 文档位于 calcbloc.com/developers。其他 CalcBloc 软件包（Python、JavaScript、PHP、R、Google Sheets，以及数据集本身）均位于 itmarkerz GitHub 组织。