acb-tax-mcp

acb-tax-mcp

一个 MCP 服务，可根据您的交易历史计算加拿大的调整后成本基础（ACB）和资本利得：包括平均成本跟踪、逐笔处置收益和虚假亏损检测，并以结构化 JSON 返回。

向您的助手询问 “我 2024 年的资本利得是多少？” 或 “我是否触发了虚假亏损规则？”，它便会根据您的交易应用 CRA 规则，无需您费力处理电子表格。

⚠️ 这只是计算辅助工具，并非税务建议。 报税前请核实每个数字；对于任何复杂情况，请咨询专业人士。请参阅限制。

适用于 Claude Desktop、Claude Code、Cursor 或任何兼容 MCP 的客户端。

---

功能

工具	功能说明
calculate_acb	完整计算：当前持仓（股份数、ACB 总额、每股 ACB）、每笔处置的收入/ACB/费用/收益、逐年汇总和警告。
acb_summary	仅显示当前持仓及其账面成本（便于根据市场价格计算未实现收益）。
capital_gains_report	单个纳税年度的 Schedule 3 风格报告：逐笔处置及总计、净资本利得和应税收益（计入比例为 50%）。
schedule3_summary	每种证券一行的汇总，列结构与 Schedule 3 完全一致：股份数、总收入、ACB、费用（佣金）、应用虚假亏损规则后的收益/亏损、购入年份和总计——这些就是您报税时实际填写的内容。
check_superficial_losses	标记受 30 天规则影响的亏损，并列出每笔事件被拒绝（递延）的金额。
unrealized_gains	根据您提供的市场价格计算当前持仓的 ACB：显示每个持仓及总未实现收益的金额和百分比（以外币报价的证券需提供价格和 fx_rate）。
normalize_broker_csv	将原始经纪商活动导出文件转换为规范交易记录：映射常见列别名（“Trade Date”“Activity Type”“Quantity”等）、保留买卖记录（DRIP 计作买入）、清理“$1,200”/“(9.95)”格式，并说明每条跳过记录的原因。

本工具实现了 CRA 的平均成本法（将某证券的所有股份计入同一个 ACB 资金池；收益根据平均成本计算，而非 FIFO）和虚假亏损规则（在出售前后 30 天内购入替代股份时，亏损不予扣除，并递延计入替代股份的 ACB）。同时支持佣金和逐笔交易的 CAD 外汇换算。

---

安装

无需安装即可试用：打开 Glama 服务页面，使用 在浏览器中试用，即可在包含几笔示例交易的沙盒中调用工具。

需要 Python 3.10+。

需要 MCP Python SDK 2.x（mcp>=2,<3）。上游已冻结 SDK 1.x 的功能，此处不再支持；最后一个可在其上运行的版本是 0.4.0。

uv tool install acb-tax-mcp      # or:  pip install acb-tax-mcp

无需安装即可从源代码运行：

git clone https://github.com/haiiibin/acb-tax-mcp
cd acb-tax-mcp
uv run acb-tax-mcp

配置客户端

Claude Desktop

在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "acb-tax": {
      "command": "acb-tax-mcp"
    }
  }
}

Claude Code

claude mcp add acb-tax -- acb-tax-mcp

---

交易

向工具提供交易列表（或 .csv / .json 文件的路径）。

字段	必填	说明
date	是	YYYY-MM-DD
action	是	buy 或 sell
security	是	股票代码 / 符号（按此键汇总）
shares	是	正数
price	是	每股价格，以交易货币计
commission	否	交易佣金（默认值为 0）
currency	否	例如 USD（默认值为 CAD）
fx_rate	否	交易货币兑 CAD 的汇率，例如 USD 取 1.35（默认值为 1）
note	否	自由文本

CSV 使用相同的列名作为标题行。如果经纪商导出的文件使用不同的标题（“Trade Date”、“Activity Type”、“Symbol”、“Quantity”……），请先使用 normalize_broker_csv 处理。

想立即试用？examples/sample_trades.csv 是一份可直接使用的经纪商风格导出文件，其中包含别名标题、带 $ 格式的数字、一条 DRIP 记录、一条股息记录（会说明原因并跳过）、一笔带汇率的 USD 交易，以及一个表面损失案例。请助手使用 normalize_broker_csv 清理文件，并对结果运行 calculate_acb。

---

用法

• “计算 ~/trades.csv 中这些交易的 ACB 和资本利得。”
• “我 2024 年的资本利得报告是什么？”
• “这些卖出交易是否触发了表面损失？”
• “XEQT 当前的账面成本是多少？”
• “这是我的 RBC 活动导出文件——请清理并计算 ACB。”
• “XEQT 的价格是 $35.20，VTI 的价格是 $305.40 USD（1.37 CAD）：我的未实现收益是多少？”

示例

// calculate_acb with:
// buy 100 XYZ @ $10, buy 100 XYZ @ $20, sell 100 XYZ @ $25
{
  "holdings": [
    { "security": "XYZ", "shares": 100.0, "total_acb": 1500.0, "acb_per_share": 15.0 }
  ],
  "dispositions": [
    { "date": "2024-03-01", "security": "XYZ", "shares_sold": 100.0,
      "proceeds": 2500.0, "acb": 1500.0, "capital_gain": 1000.0,
      "is_superficial_loss": false }
  ],
  "summary": {
    "by_tax_year": [
      { "tax_year": 2024, "net_capital_gain": 1000.0, "taxable_capital_gain": 500.0 }
    ],
    "inclusion_rate": 0.5
  }
}

表面损失示例

以每股 $10 买入 100 股，以每股 $8 卖出 100 股（亏损 $200），然后在 9 天后以每股 $8 重新买入 100 股：

{ "gain_before_superficial": -200.0, "superficial_loss_denied": 200.0,
  "capital_gain": 0.0, "is_superficial_loss": true }

这 $200 的亏损不予认可，并计入重新买入股份的 ACB（每股新的 ACB 变为 $10），因此可在未来卖出时收回。

---

限制

依赖输出结果前，请先阅读以下内容。

• 按相同财产采用平均成本法。 请将同一证券在所有账户中的全部交易一起提供，因为 CRA 规则要求在纳税人层面汇总相同财产。工具会按你提供的 security 键进行汇总。
• 表面损失采用标准的三者取最小值测试，并仅进行一次正向遍历。存在深度链式或相互重叠的表面损失时，可能需要专业人士逐案判断。
• 尚未处理： 资本返还、再投资 / 名义分配（ETF 虚拟分配）、股票拆分、期权及其他公司行为。这些会影响 ACB，已列入路线图。
• 汇率必须按每笔交易提供（使用交易日的汇率）。工具不会获取汇率。
• 注册账户（TFSA/RRSP）不产生资本利得；此工具适用于**非注册（应税）**账户。
• 不构成税务建议。

---

开发

uv venv
uv pip install -e ".[dev]"
uv run pytest

许可证

MIT。请参阅 LICENSE。