mcpField
C
china-tax-loss-harvesting

china-tax-loss-harvesting

github.com/jwangkunOther87569 installsUpdated 6w ago
Repository

About china-tax-loss-harvesting

A tax-loss harvesting skill for Chinese equity portfolios. It guides users through identifying unrealized losses, assessing potential offsets, choosing replacement securities, and documenting trades, with A-share tax and year-end considerations.

Key features

  1. 01Screen holdings for unrealized losses
  2. 02Assess potential tax effects of loss offsets
  3. 03Identify replacement securities
  4. 04Plan sales and replacement trades
  5. 05Prepare filing records and year-end checklist

Use cases

  1. 01Review portfolio loss positions before year-end
  2. 02Assess offsetting losses against gains in the same year
  3. 03Choose replacement securities during rebalancing
  4. 04Organize trade records for tax filing

MCP support

The skill describes fetching quotes and historical data through iFind MCP or AkShare MCP, with IFIND_DATA_SOURCE_MODE controlling data-source preference.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/jwangkun/claude-for-financial-services-cn --skill china-tax-loss-harvesting

After installing, type/china-tax-loss-harvestingin Claude Code to confirm it loaded.

Details

From the project README

china-tax-loss-harvesting

Purpose

Implement A股税务亏损抵扣 — systematic tax-loss harvesting for Chinese investment portfolios.

Data Sources

Primary: iFind MCP (Tier-1 付费) / AkShare MCP (Tier-2 免费备选)
get_quote(ticker)                     → Current prices for holdings
get_historical_data(ticker)           → Cost basis / purchase history
Secondary Sources
  • Broker records — cost basis, trade history
  • Tax filings — prior year losses
  • 交易所 — tax treatment rules

Workflow

Step 1: Identify Tax-Loss Positions

Loss identification:

PositionTickerCost BasisCurrent ValueUnrealized LossLoss %
¥XX¥XX¥XXX%

Loss screening criteria:

  • Unrealized loss > 10% of cost basis
  • Loss amount significant relative to portfolio
  • Holding period appropriate for tax treatment
Step 2: Understand A-share Tax Rules

China tax treatment for securities:

ItemTax RateNotes
证券买卖价差暂免 (temporarily exempt)Capital gains on stocks
股息红利20% (持股>1年减半至10%, >1年免征)Dividend tax
基金分红暂免 (some funds)Fund distributions
买卖印花税0.05% (seller only)Stamp duty
证券交易佣金0.02-0.03%Commission

Current status of capital gains tax:

  • Individuals: Capital gains on stocks are currently temporarily exempt (暂免征收)
  • However, losses can be used to offset gains within the same year
  • Loss carryforward rules may apply
Step 3: Calculate Tax Benefit

Tax benefit calculation:

ScenarioGainLossTaxable GainTax Saved
Without TLH¥XX—¥XX—
With TLH¥XX¥XX¥XX¥XX
Benefit¥XX

Note: In the current A-share environment where capital gains are largely exempt, tax-loss harvesting benefits may be limited. However:

  • Harvesting losses can be valuable if tax rules change
  • Offsetting gains within the same year
  • Potential future tax benefit if capital gains tax is introduced
Step 4: Identify Replacement Securities

Replacement criteria:

CriterionRequirement
Same sectorSimilar industry exposure
Similar characteristicsMarket cap, growth, quality
Not substantially identicalAvoid wash sale rules
Tax-efficientConsider dividend treatment

Wash sale considerations (China):

  • No explicit wash sale rule currently
  • However, substantially identical securities may be disallowed
  • Best practice: 30-day waiting period
Step 5: Execution Strategy

Execution options:

StrategyDescriptionProsCons
Full exitSell and replaceClean loss realizationMarket risk
Partial exitReduce positionPartial benefitPartial benefit only
SwapSell loss, buy similarMaintain exposureTiming risk
DelayWait for recoveryNo transaction costsMissed opportunity
Step 6: Implementation Plan

Step-by-step plan:

StepActionTiming
1Identify loss positionsPre-year-end
2Evaluate replacement optionsPre-year-end
3Check wash sale rulesPre-year-end
4Execute salesBefore year-end
5Execute purchasesAfter sale (or simultaneously)
6Document transactionsImmediately
7File tax formsTax filing deadline
Step 7: Document for Tax Filing

Required documentation:

DocumentContent
Trade confirmationsSale and purchase tickets
Cost basis recordsPurchase prices, dates
Loss calculationsRealized loss amounts
Replacement securitiesIdentified alternatives
Market rationaleInvestment thesis
Step 8: Year-End Checklist

Year-end TLH checklist:

DateAction
NovReview portfolio for loss positions
Dec 1-15Identify replacement securities
Dec 15-20Execute loss sales
Dec 20-31Execute replacements
Dec 31Final portfolio review
JanFile tax documentation

China-Specific TLH Considerations

Current Tax Environment
FactorStatusImplication
资本利得税暂免 (temporarily exempt)Limited current benefit
印花税0.05%Cost on sale
股息红利税20% (10% for >1yr)Consider in replacement
交易佣金0.02-0.03%Trading cost
When TLH Makes Sense in China
ScenarioBenefit
Offset short-term gainsUse losses against gains
Reset cost basisLower future gains if taxed
Prepare for tax changesIf capital gains taxed in future
Portfolio rebalancingCombine with rebalancing
A-share Market Timing
ConsiderationGuidance
年末效应Year-end selling pressure
涨跌停限制May prevent execution
流动性Ensure liquidity for exit
政策窗口Tax policy change risk

TLH for Different Client Types

Individual Investors
ConsiderationGuidance
持股期限>1 year for dividend tax benefit
高频交易May trigger scrutiny
金额门槛Focus on significant positions
Institutional Investors
ConsiderationGuidance
交易成本Factor in commission impact
市场冲击Large position impact
会计处理NAV impact timing
合规审查Documentation requirements

Quality Checks

Before executing:

  • Loss positions identified
  • Tax benefit calculated
  • Replacement securities identified
  • Wash sale rules considered
  • Execution plan clear
  • Documentation prepared
  • Timing appropriate

Data Source Mode Switch: Set env var IFIND_DATA_SOURCE_MODE to control data source preference.

  • ifind-only (strict): Use iFind only, error if unavailable
  • ifind-fallback (default): iFind preferred, fallback to AkShare
  • akshare-only, wind-only (Wind only), wind-fallback (Wind first, fallback to iFind → AkShare): Skip iFind, use AkShare only

Comments

Markdown supported