Skip to content
Back to search

chinataxcalc

Calculate China expat IIT net salary, BIA tax-free allowances, annual bonus & GBA 15% rebates.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/abigaildavised--chinataxcalc-mcp/badge.svg)](/listings/abigaildavised--chinataxcalc-mcp)

HTML

<a href="/listings/abigaildavised--chinataxcalc-mcp"><img src="/api/listings/abigaildavised--chinataxcalc-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 32 lines
  1. {
  2. "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  3. "name": "chinataxcalc",
  4. "version": "1.0.0",
  5. "description": "Calculate China expat IIT net salary, BIA tax-free allowances, annual bonus & GBA 15% rebates.",
  6. "homepage": "https://chinataxcalc.com",
  7. "repository": "https://github.com/AbigailDavised/chinataxcalc-mcp",
  8. "license": "MIT",
  9. "author": {
  10. "name": "Abigail Davised",
  11. "email": "admin@chinataxcalc.com",
  12. "url": "https://chinataxcalc.com"
  13. },
  14. "keywords": [
  15. "china-tax",
  16. "expat-salary",
  17. "iit-calculator",
  18. "bia-allowances",
  19. "gba-subsidy",
  20. "mcp"
  21. ],
  22. "mcpServers": "./.mcp.json",
  23. "extensions": {
  24. "com.nousresearch.hermes": {
  25. "servers": {
  26. "chinataxcalc": {
  27. "trust": "untrusted"
  28. }
  29. }
  30. }
  31. }
  32. }
README.md · README · 145 lines
  1. # ChinaTaxCalc MCP Server — China Expat IIT, BIA Allowance, Annual Bonus & GBA 15% Rebate Engine
  2. <p align="center">
  3. <img src="./assets/logo.svg" alt="ChinaTaxCalc Logo" width="80" height="80" />
  4. </p>
  5. ## Overview & Production Architecture
  6. **ChinaTaxCalc** ([https://chinataxcalc.com](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.
  7. ## Available MCP Tools (8 Read-Only Tools)
  8. | Tool Name | Purpose & Deterministic Engine | Key Parameters | Safety |
  9. | :--- | :--- | :--- | :---: |
  10. | `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` |
  11. | `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` |
  12. | `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` |
  13. | `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` |
  14. | `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` |
  15. | `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` |
  16. | `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` |
  17. | `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` |
  18. ## Live JSON-RPC 2.0 Verification Sample
  19. Request (`POST https://chinataxcalc.com/api/mcp`):
  20. ```bash
  21. curl -s -X POST https://chinataxcalc.com/api/mcp \
  22. -H "Content-Type: application/json" \
  23. -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}}}'
  24. ```
  25. Verified Production Response:
  26. ```json
  27. {
  28. "sourceEngine": "src/utils/taxCalculations.ts (calculateExpatIIT)",
  29. "cityProfile": {
  30. "id": "shanghai",
  31. "name": "Shanghai",
  32. "minSocialBaseRMB": 7310,
  33. "maxSocialBaseRMB": 36549,
  34. "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."
  35. },
  36. "exchangeRateToRMB": 1,
  37. "standardAnnualDeductionRMB": 60000,
  38. "summary": {
  39. "currency": "RMB",
  40. "annualNetPay": 571440,
  41. "monthlyNetPay": 47620,
  42. "annualIIT": 58560,
  43. "monthlyIIT": 4880,
  44. "annualSocialSecurityEmployee": 0,
  45. "effectiveTaxRatePct": 9.3,
  46. "marginalTaxBracketPct": 25,
  47. "netTakeHomePct": 90.7,
  48. "taxSavingsFromBIA": 39000,
  49. "annualEmployerCost": 630000
  50. },
  51. "rmbBreakdown": {
  52. "totalAnnualGrossRMB": 630000,
  53. "totalAnnualBIARMB": 144000,
  54. "annualTaxableIncomeRMB": 336000,
  55. "annualComprehensiveIITRMB": 52080,
  56. "annualBonusIITRMB": 6480,
  57. "totalAnnualIITRMB": 58560,
  58. "totalAnnualNetPayRMB": 571440,
  59. "taxSavingsFromBIARMB": 39000
  60. },
  61. "calculatorUrl": "https://chinataxcalc.com"
  62. }
  63. ```
  64. ## Quick Client Configuration (Claude Desktop / Cursor / Windsurf / Gemini CLI / Hermes)
  65. ```json
  66. {
  67. "mcpServers": {
  68. "chinataxcalc": {
  69. "type": "http",
  70. "url": "https://chinataxcalc.com/api/mcp"
  71. }
  72. }
  73. }
  74. ```
  75. Or run directly from any Node.js terminal via the pinned official CLI:
  76. ```bash
  77. npx -y chinataxcalc-cli@1.0.0 tools
  78. npx -y chinataxcalc-cli@1.0.0 demo
  79. ```
  80. ## Statutory Compliance & Tax Reference Matrices
  81. ### China Comprehensive Income 7-Tier Progressive IIT Brackets (Standard Deduction: ¥60,000/yr)
  82. | Level | Annual Taxable Income (RMB) | Statutory Marginal Rate | Quick Deduction (RMB) | Statutory Basis |
  83. | :---: | :--- | :---: | :---: | :--- |
  84. | **1** | `¥0 – ¥36,000` | **`3%`** | `¥0` | PRC IIT Law (Comprehensive Income) |
  85. | **2** | `¥36,001 – ¥144,000` | **`10%`** | `¥2,520` | PRC IIT Law / STA [2018] No. 56 |
  86. | **3** | `¥144,001 – ¥300,000` | **`20%`** | `¥16,920` | PRC IIT Law / STA [2018] No. 56 |
  87. | **4** | `¥300,001 – ¥420,000` | **`25%`** | `¥31,920` | PRC IIT Law / STA [2018] No. 56 |
  88. | **5** | `¥420,001 – ¥660,000` | **`30%`** | `¥52,920` | PRC IIT Law / STA [2018] No. 56 |
  89. | **6** | `¥660,001 – ¥960,000` | **`35%`** | `¥85,920` | PRC IIT Law / STA [2018] No. 56 |
  90. | **7** | `Exceeding ¥960,000` | **`45%`** | `¥181,920` | PRC IIT Law / Top Marginal Bracket |
  91. ### Six-City Expat Social Insurance Base Caps & Policy Matrix
  92. | Municipality | Social Average Wage (RMB/mo) | Contribution Base Floor | Contribution Base Ceiling (3x) | Expat Participation & Regional Tax Rules |
  93. | :--- | :---: | :---: | :---: | :--- |
  94. | **Shanghai** | `¥12,183` | `¥7,310` | `¥36,549` | Historical opt-out flexibility under Hu Ren She Han [2021] No. 272 |
  95. | **Beijing** | `¥11,761` | `¥6,326` | `¥35,283` | Strictly mandatory unless covered by bilateral totalization treaty |
  96. | **Shenzhen** | `¥8,807` | `¥4,404` | `¥26,421` | Qianhai / GBA 15% effective IIT fiscal subsidy (capped RMB 5M/yr) |
  97. | **Guangzhou** | `¥8,807` | `¥5,284` | `¥26,421` | Nansha / Huangpu 15% IIT ceiling rebate for verified overseas talent |
  98. | **Hangzhou** | `¥8,023` | `¥4,814` | `¥24,069` | Mandatory municipal contribution rules up to 300% cap |
  99. | **Chengdu** | `¥7,356` | `¥4,414` | `¥22,068` | Mandatory social insurance with Western China talent incentives |
  100. ### Eight Statutory Expat Tax-Exempt BIA Allowances (MOF/STA Announcement [2023] No. 29 · Through Dec 31, 2027)
  101. | Allowance Category | Documentation Requirement | Payroll Treatment & Key Caution |
  102. | :--- | :--- | :--- |
  103. | **Housing Rental** | Official tax bureau VAT rental Fapiao | Direct tax-base deduction; analyze landlord Fapiao fee ROI vs marginal tax rate |
  104. | **Children Education** | Accredited school tuition invoice inside China | Must match non-cash direct payment or genuine Fapiao reimbursement |
  105. | **Language Training** | Accredited Mandarin school receipt | Eligible for bona fide language instruction for the foreign assignee |
  106. | **Home Leave Flights** | Airline itinerary + Fapiao (up to 2 round trips/yr) | Covers economy/business fare between work city in China and home country |
  107. | **Meal & Laundry Allowances** | Corporate receipts / legitimate VAT Fapiao | Must be reasonable and non-cash fixed subsidy |
  108. | **Relocation & Travel Per Diem** | Moving invoices / business travel policy receipts | Documented arrival, departure, or business travel costs remain non-taxable |
  109. ## Official Web Calculators & Regulatory Guides
  110. - **[ChinaTaxCalc Official Portal — China Expat IIT & Net Salary Calculator](https://chinataxcalc.com)** — `https://chinataxcalc.com`
  111. - **[Expat Tax-Exempt BIA Housing & Education Allowances (No. 29)](https://chinataxcalc.com/expat-allowances-bia)** — `https://chinataxcalc.com/expat-allowances-bia`
  112. - **[Annual One-Off Bonus Tax Cliff & Separate Filing (No. 30)](https://chinataxcalc.com/annual-bonus-tax)** — `https://chinataxcalc.com/annual-bonus-tax`
  113. - **[Shanghai Expat IIT & Social Security Exemption Simulator](https://chinataxcalc.com/shanghai-expat-tax)** — `https://chinataxcalc.com/shanghai-expat-tax`
  114. - **[2026/2027 China 7-Bracket Individual Income Tax Rates Reference](https://chinataxcalc.com/tax-brackets)** — `https://chinataxcalc.com/tax-brackets`
  115. - **[Cross-Border Relocation Tax Benchmark (China vs US/UK/DE/SG/HK)](https://chinataxcalc.com/relocation)** — `https://chinataxcalc.com/relocation`
  116. - **[Greater Bay Area 15% Overseas Talent Fiscal Subsidy Calculator](https://chinataxcalc.com/gba-subsidy)** — `https://chinataxcalc.com/gba-subsidy`
  117. - **[China 6-Year Worldwide Tax Exemption & 31-Day Reset Diagnostic](https://chinataxcalc.com/six-year-rule)** — `https://chinataxcalc.com/six-year-rule`
  118. - **[Foreign Expat Salary Repatriation & SAFE Circular [2020] No. 14 Guide](https://chinataxcalc.com/repatriation)** — `https://chinataxcalc.com/repatriation`
  119. ## License
  120. MIT License — maintained by **[ChinaTaxCalc](https://chinataxcalc.com)**.

Version history

  • v1.0.011/22/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.