Skip to main content
Glama
ChinaTaxCalc MCP Server

ChinaTaxCalc MCP Server

ChinaTaxCalc MCP Server — China Expat IIT, BIA Allowance, Annual Bonus & GBA 15% Rebate Engine

Overview & Production Architecture

ChinaTaxCalc (https://chinataxcalc.com) exposes a stateless, zero-authentication Model Context Protocol (MCP) server (streamable-http at https://chinataxcalc.com/api/mcp) backed directly by mainland China Individual Income Tax (IIT) engines, MOF/STA Announcements [2023] No. 29 (tax-exempt expat BIA housing and international school tuition through 2027) and [2023] No. 30 (annual one-off bonus separate calculation & cliff dead-zone detection), STA [2018] No. 56 12-month cumulative withholding simulations, six municipal social insurance caps, nine Greater Bay Area 15% fiscal rebate hubs, seven international relocation benchmarks (US-CA, US-NY, US-TX, UK, DE, SG, HK), the 6-year worldwide tax 31-day reset rule, and SAFE Circular [2020] No. 14 salary repatriation bank checklists. All 8 tools are public and annotated readOnlyHint: true with no API keys required.

Related MCP server: China Shebao & Payroll Tax MCP

Available MCP Tools (8 Read-Only Tools)

Tool Name

Purpose & Deterministic Engine

Key Parameters

Safety

calculate_china_expat_iit_and_net_salary

Compute annual and monthly net take-home cash, marginal brackets, employer costs, and tax savings from eight Fapiao-backed BIA allowances across

grossAmount*, incomePeriod, currency, cityId (+4 more)

readOnly

simulate_cumulative_monthly_withholding

Simulate January-to-December paycheck variance under STA Announcement 2018 No. 56, highlighting bracket jump months and lumpy school tuition spik

monthlyGrossRMB*, monthlySSRMB, monthlyBIARMB, lumpyTuitionMode (+1 more)

readOnly

compare_annual_bonus_separate_vs_combined_tax

Contrast MOF/STA Announcement 30 separate bonus taxation against combined comprehensive filing and warn about statutory bracket cliff traps.

annualTaxableSalaryRMB, annualBonusRMB

readOnly

analyze_landlord_fapiao_surcharge_roi

Evaluate whether paying a landlord surcharge to obtain official housing VAT invoices generates positive after-tax savings at your marginal rate.

monthlyRentRMB, surchargeRatePct, marginalRate*

readOnly

calculate_gba_15pct_talent_tax_subsidy

Quantify municipal fiscal refunds across nine Greater Bay Area hubs like Shenzhen Qianhai and Guangzhou Nansha where effective burden caps at 15

actualIITPaidRMB, taxableIncomeRMB, gbaCityId

readOnly

compare_cross_border_relocation_net_pay

Benchmark equivalent USD compensation across seven global financial hubs against Shanghai expat net pay with cost-of-living index comparisons.

grossUSD*, comparisonHubs, chinaCityId, chinaHousingAllowanceUSD

readOnly

diagnose_six_year_worldwide_tax_rule

Track consecutive 183-day residency years and verify whether a continuous 30+ day absence resets non-domiciled offshore income protection.

records*

readOnly

generate_safe_salary_repatriation_checklist

Assemble the six mandatory counter verification items, Tax App registration tips, and bilingual SAFE quota exemption text for wiring RMB abroad.

remitAmountRMB, targetCurrency

readOnly

Live JSON-RPC 2.0 Verification Sample

Request (POST https://chinataxcalc.com/api/mcp):

curl -s -X POST https://chinataxcalc.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate_china_expat_iit_and_net_salary","arguments":{"grossAmount":45000,"incomePeriod":"monthly","currency":"RMB","cityId":"shanghai","socialSecurityMode":"exempt","annualBonus":90000,"housingRental":12000}}}'

Verified Production Response:

{
  "sourceEngine": "src/utils/taxCalculations.ts (calculateExpatIIT)",
  "cityProfile": {
    "id": "shanghai",
    "name": "Shanghai",
    "minSocialBaseRMB": 7310,
    "maxSocialBaseRMB": 36549,
    "notes": "Expat Social Security exemption is historically supported in Shanghai (Hu Ren She Han [2021] No. 272). Foreign hires may mutually agree with employers to opt out."
  },
  "exchangeRateToRMB": 1,
  "standardAnnualDeductionRMB": 60000,
  "summary": {
    "currency": "RMB",
    "annualNetPay": 571440,
    "monthlyNetPay": 47620,
    "annualIIT": 58560,
    "monthlyIIT": 4880,
    "annualSocialSecurityEmployee": 0,
    "effectiveTaxRatePct": 9.3,
    "marginalTaxBracketPct": 25,
    "netTakeHomePct": 90.7,
    "taxSavingsFromBIA": 39000,
    "annualEmployerCost": 630000
  },
  "rmbBreakdown": {
    "totalAnnualGrossRMB": 630000,
    "totalAnnualBIARMB": 144000,
    "annualTaxableIncomeRMB": 336000,
    "annualComprehensiveIITRMB": 52080,
    "annualBonusIITRMB": 6480,
    "totalAnnualIITRMB": 58560,
    "totalAnnualNetPayRMB": 571440,
    "taxSavingsFromBIARMB": 39000
  },
  "calculatorUrl": "https://chinataxcalc.com"
}

Quick Client Configuration (Claude Desktop / Cursor / Windsurf / Gemini CLI / Hermes)

{
  "mcpServers": {
    "chinataxcalc": {
      "type": "http",
      "url": "https://chinataxcalc.com/api/mcp"
    }
  }
}

Or run directly from any Node.js terminal via the pinned official CLI:

npx -y chinataxcalc-cli@1.0.0 tools
npx -y chinataxcalc-cli@1.0.0 demo

Statutory Compliance & Tax Reference Matrices

China Comprehensive Income 7-Tier Progressive IIT Brackets (Standard Deduction: ¥60,000/yr)

Level

Annual Taxable Income (RMB)

Statutory Marginal Rate

Quick Deduction (RMB)

Statutory Basis

1

¥0 – ¥36,000

3%

¥0

PRC IIT Law (Comprehensive Income)

2

¥36,001 – ¥144,000

10%

¥2,520

PRC IIT Law / STA [2018] No. 56

3

¥144,001 – ¥300,000

20%

¥16,920

PRC IIT Law / STA [2018] No. 56

4

¥300,001 – ¥420,000

25%

¥31,920

PRC IIT Law / STA [2018] No. 56

5

¥420,001 – ¥660,000

30%

¥52,920

PRC IIT Law / STA [2018] No. 56

6

¥660,001 – ¥960,000

35%

¥85,920

PRC IIT Law / STA [2018] No. 56

7

Exceeding ¥960,000

45%

¥181,920

PRC IIT Law / Top Marginal Bracket

Six-City Expat Social Insurance Base Caps & Policy Matrix

Municipality

Social Average Wage (RMB/mo)

Contribution Base Floor

Contribution Base Ceiling (3x)

Expat Participation & Regional Tax Rules

Shanghai

¥12,183

¥7,310

¥36,549

Historical opt-out flexibility under Hu Ren She Han [2021] No. 272

Beijing

¥11,761

¥6,326

¥35,283

Strictly mandatory unless covered by bilateral totalization treaty

Shenzhen

¥8,807

¥4,404

¥26,421

Qianhai / GBA 15% effective IIT fiscal subsidy (capped RMB 5M/yr)

Guangzhou

¥8,807

¥5,284

¥26,421

Nansha / Huangpu 15% IIT ceiling rebate for verified overseas talent

Hangzhou

¥8,023

¥4,814

¥24,069

Mandatory municipal contribution rules up to 300% cap

Chengdu

¥7,356

¥4,414

¥22,068

Mandatory social insurance with Western China talent incentives

Eight Statutory Expat Tax-Exempt BIA Allowances (MOF/STA Announcement [2023] No. 29 · Through Dec 31, 2027)

Allowance Category

Documentation Requirement

Payroll Treatment & Key Caution

Housing Rental

Official tax bureau VAT rental Fapiao

Direct tax-base deduction; analyze landlord Fapiao fee ROI vs marginal tax rate

Children Education

Accredited school tuition invoice inside China

Must match non-cash direct payment or genuine Fapiao reimbursement

Language Training

Accredited Mandarin school receipt

Eligible for bona fide language instruction for the foreign assignee

Home Leave Flights

Airline itinerary + Fapiao (up to 2 round trips/yr)

Covers economy/business fare between work city in China and home country

Meal & Laundry Allowances

Corporate receipts / legitimate VAT Fapiao

Must be reasonable and non-cash fixed subsidy

Relocation & Travel Per Diem

Moving invoices / business travel policy receipts

Documented arrival, departure, or business travel costs remain non-taxable

Official Web Calculators & Regulatory Guides

License

MIT License — maintained by ChinaTaxCalc.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables geographic parity analysis with 26 read-only tools covering purchasing power, salary localization, cost of living, nomad visas, tax residency, FIRE planning, and relocation costs.
      13 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying provincial social security policies and city housing-fund limits, calculating take-home salary, income tax, annual bonus tax options, and retirement pension estimates across China.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables clients to access deterministic, read-only China inbound-compliance tools for work-permit scoring, customs medication screening, expat tax simulation, visa-free and transit eligibility, apostille workflows, essential app and payment setup, attraction entry requirements, and CAAC power-bank and payment fee calculations.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables stateless, read-only calculation and comparison of China SAFEA work-permit points, score-deficit options, expat IIT scenarios, job-transfer deadlines, apostille requirements, municipal policies, fast-track pathways, and Z-visa execution roadmaps through eight deterministic tools.
      MIT