Back to search
chinataxcalc
SkillWorks with Claude CodeGitHub
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
Markdown
[](/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
- {
- "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
- "name": "chinataxcalc",
- "version": "1.0.0",
- "description": "Calculate China expat IIT net salary, BIA tax-free allowances, annual bonus & GBA 15% rebates.",
- "homepage": "https://chinataxcalc.com",
- "repository": "https://github.com/AbigailDavised/chinataxcalc-mcp",
- "license": "MIT",
- "author": {
- "name": "Abigail Davised",
- "email": "admin@chinataxcalc.com",
- "url": "https://chinataxcalc.com"
- },
- "keywords": [
- "china-tax",
- "expat-salary",
- "iit-calculator",
- "bia-allowances",
- "gba-subsidy",
- "mcp"
- ],
- "mcpServers": "./.mcp.json",
- "extensions": {
- "com.nousresearch.hermes": {
- "servers": {
- "chinataxcalc": {
- "trust": "untrusted"
- }
- }
- }
- }
- }
README.md · README · 145 lines
- # ChinaTaxCalc MCP Server — China Expat IIT, BIA Allowance, Annual Bonus & GBA 15% Rebate Engine
- <p align="center">
- <img src="./assets/logo.svg" alt="ChinaTaxCalc Logo" width="80" height="80" />
- </p>
- ## Overview & Production Architecture
- **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.
- ## 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`):
- ```bash
- 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:
- ```json
- {
- "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)
- ```json
- {
- "mcpServers": {
- "chinataxcalc": {
- "type": "http",
- "url": "https://chinataxcalc.com/api/mcp"
- }
- }
- }
- ```
- Or run directly from any Node.js terminal via the pinned official CLI:
- ```bash
- 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
- - **[ChinaTaxCalc Official Portal — China Expat IIT & Net Salary Calculator](https://chinataxcalc.com)** — `https://chinataxcalc.com`
- - **[Expat Tax-Exempt BIA Housing & Education Allowances (No. 29)](https://chinataxcalc.com/expat-allowances-bia)** — `https://chinataxcalc.com/expat-allowances-bia`
- - **[Annual One-Off Bonus Tax Cliff & Separate Filing (No. 30)](https://chinataxcalc.com/annual-bonus-tax)** — `https://chinataxcalc.com/annual-bonus-tax`
- - **[Shanghai Expat IIT & Social Security Exemption Simulator](https://chinataxcalc.com/shanghai-expat-tax)** — `https://chinataxcalc.com/shanghai-expat-tax`
- - **[2026/2027 China 7-Bracket Individual Income Tax Rates Reference](https://chinataxcalc.com/tax-brackets)** — `https://chinataxcalc.com/tax-brackets`
- - **[Cross-Border Relocation Tax Benchmark (China vs US/UK/DE/SG/HK)](https://chinataxcalc.com/relocation)** — `https://chinataxcalc.com/relocation`
- - **[Greater Bay Area 15% Overseas Talent Fiscal Subsidy Calculator](https://chinataxcalc.com/gba-subsidy)** — `https://chinataxcalc.com/gba-subsidy`
- - **[China 6-Year Worldwide Tax Exemption & 31-Day Reset Diagnostic](https://chinataxcalc.com/six-year-rule)** — `https://chinataxcalc.com/six-year-rule`
- - **[Foreign Expat Salary Repatriation & SAFE Circular [2020] No. 14 Guide](https://chinataxcalc.com/repatriation)** — `https://chinataxcalc.com/repatriation`
- ## License
- 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 inFree to use. If it’s helped, pass it on.