{
  "markdown": "# acb-tax-mcp\n\n<!-- mcp-name: io.github.haiiibin/acb-tax-mcp -->\n\n[![CI](https://github.com/haiiibin/acb-tax-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/haiiibin/acb-tax-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/acb-tax-mcp)](https://pypi.org/project/acb-tax-mcp/)\n[![PyPI Downloads](https://img.shields.io/pypi/dm/acb-tax-mcp)](https://pypi.org/project/acb-tax-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/acb-tax-mcp)](https://pypi.org/project/acb-tax-mcp/)\n[![Glama](https://glama.ai/mcp/servers/haiiibin/acb-tax-mcp/badges/score.svg)](https://glama.ai/mcp/servers/haiiibin/acb-tax-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.haiiibin%2Facb--tax--mcp-6d4aff)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.haiiibin/acb-tax-mcp&version=latest)\n[![Listed in awesome-mcp-servers](https://img.shields.io/badge/awesome--mcp--servers-listed-8A2BE2)](https://github.com/punkpeye/awesome-mcp-servers)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n> An [MCP](https://modelcontextprotocol.io) server that computes Canadian **adjusted cost base (ACB)** and **capital gains** from your trade history: average-cost tracking, per-disposition gains, and **superficial-loss** detection, returned as structured JSON.\n\nAsk your assistant *\"what are my capital gains for 2024?\"* or *\"did I trigger any superficial losses?\"* and it runs the CRA rules over your transactions instead of you wrestling a spreadsheet.\n\n> ⚠️ **This is a calculation aid, not tax advice.** Verify every number before you file, and consult a professional for anything non-trivial. See [Limitations](#limitations).\n\n![acb-tax-mcp demo: one prompt cleans a broker export, reports 2025 capital gains and flags a superficial loss](docs/demo.gif)\n\nWorks with **Claude Desktop**, **Claude Code**, **Cursor**, or any MCP-compatible client.\n\n---\n\n## Features\n\n| Tool | What it does |\n|---|---|\n| `calculate_acb` | Full calculation: current holdings (shares, total ACB, ACB per share), every disposition with proceeds/ACB/outlays/gain, per-year summaries, and warnings. |\n| `acb_summary` | Just current holdings and their book cost (handy for unrealized gains against a market price). |\n| `capital_gains_report` | A Schedule-3-style report for one tax year: each disposition plus totals, net capital gain, and taxable gain (50% inclusion). |\n| `schedule3_summary` | One aggregated row per security in the exact Schedule 3 column shape: shares, gross proceeds, ACB, outlays (commissions), gain/loss after the superficial-loss rule, acquisition years, and totals -- the lines you actually transcribe when filing. |\n| `check_superficial_losses` | Flags losses caught by the 30-day rule, with the denied (deferred) amount per event. |\n| `unrealized_gains` | Current holdings' ACB against market prices you supply: per-position and total unrealized gain in dollars and percent (foreign-quoted securities take a price + fx_rate pair). |\n| `normalize_broker_csv` | Turns a raw broker activity export into clean transactions: maps common column aliases (\"Trade Date\", \"Activity Type\", \"Quantity\"...), keeps buy/sell rows (DRIP counts as a buy), cleans \"$1,200\"/\"(9.95)\" formats, and reports every skipped row with a reason. |\n\nImplements the CRA **average-cost method** (all shares of a security pool into one ACB; gains are against the average, not FIFO) and the **superficial-loss rule** (loss denied and deferred into the ACB of substitute shares bought within 30 days before or after the sale). Commissions and per-trade **CAD FX conversion** are handled.\n\n---\n\n## Install\n\nNo install needed to try it: open the [Glama server page](https://glama.ai/mcp/servers/haiiibin/acb-tax-mcp) and use **Try in Browser** to call the tools against a sandbox with a couple of sample transactions.\n\nRequires Python 3.10+.\n\n```bash\nuv tool install acb-tax-mcp      # or:  pip install acb-tax-mcp\n```\n\nRun from source without installing:\n\n```bash\ngit clone https://github.com/haiiibin/acb-tax-mcp\ncd acb-tax-mcp\nuv run acb-tax-mcp\n```\n\n## Configure your client\n\n### Claude Desktop\n\nIn `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"acb-tax\": {\n      \"command\": \"acb-tax-mcp\"\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add acb-tax -- acb-tax-mcp\n```\n\n---\n\n## Transactions\n\nGive the tools a list of transactions (or a path to a `.csv` / `.json` file).\n\n| Field | Required | Notes |\n|---|---|---|\n| `date` | yes | `YYYY-MM-DD` |\n| `action` | yes | `buy` or `sell` |\n| `security` | yes | ticker / symbol (pooled by this key) |\n| `shares` | yes | positive number |\n| `price` | yes | price per share, in the trade currency |\n| `commission` | no | trade commission (default 0) |\n| `currency` | no | e.g. `USD` (default `CAD`) |\n| `fx_rate` | no | trade currency to CAD, e.g. `1.35` for USD (default 1) |\n| `note` | no | free text |\n\nCSV uses the same column names as a header row. If your broker's export uses different headers (\"Trade Date\", \"Activity Type\", \"Symbol\", \"Quantity\"...), run it through `normalize_broker_csv` first.\n\nWant something to try immediately? [`examples/sample_trades.csv`](examples/sample_trades.csv) is a ready-made broker-style export with aliased headers, `$`-formatted numbers, a DRIP row, a dividend row (skipped with a reason), a USD trade with FX, and a superficial-loss scenario. Ask your assistant to clean it with `normalize_broker_csv` and run `calculate_acb` on the result.\n\n---\n\n## Usage\n\n- *\"Calculate the ACB and capital gains for the trades in `~/trades.csv`.\"*\n- *\"What's my capital-gains report for 2024?\"*\n- *\"Did any of these sales trigger a superficial loss?\"*\n- *\"What's my current book cost for XEQT?\"*\n- *\"Here's my RBC activity export -- clean it up and compute my ACB.\"*\n- *\"XEQT is at $35.20 and VTI at $305.40 USD (1.37 CAD): what are my unrealized gains?\"*\n\n### Example\n\n```jsonc\n// calculate_acb with:\n// buy 100 XYZ @ $10, buy 100 XYZ @ $20, sell 100 XYZ @ $25\n{\n  \"holdings\": [\n    { \"security\": \"XYZ\", \"shares\": 100.0, \"total_acb\": 1500.0, \"acb_per_share\": 15.0 }\n  ],\n  \"dispositions\": [\n    { \"date\": \"2024-03-01\", \"security\": \"XYZ\", \"shares_sold\": 100.0,\n      \"proceeds\": 2500.0, \"acb\": 1500.0, \"capital_gain\": 1000.0,\n      \"is_superficial_loss\": false }\n  ],\n  \"summary\": {\n    \"by_tax_year\": [\n      { \"tax_year\": 2024, \"net_capital_gain\": 1000.0, \"taxable_capital_gain\": 500.0 }\n    ],\n    \"inclusion_rate\": 0.5\n  }\n}\n```\n\n### Superficial loss example\n\nBuy 100 @ $10, sell 100 @ $8 (a $200 loss), then rebuy 100 @ $8 nine days later:\n\n```jsonc\n{ \"gain_before_superficial\": -200.0, \"superficial_loss_denied\": 200.0,\n  \"capital_gain\": 0.0, \"is_superficial_loss\": true }\n```\n\nThe $200 loss is denied and added to the ACB of the repurchased shares (new ACB per share becomes $10), so it is recovered on a future sale.\n\n---\n\n## Limitations\n\nRead these before relying on the output.\n\n- **Average-cost, per identical property.** Feed *all* trades of the same security across your accounts together, since the CRA rule pools identical property at the taxpayer level. The tool pools by the `security` key you provide.\n- **Superficial losses** use the standard least-of-three test with a single forward pass. Deeply chained or overlapping superficial losses can need case-by-case professional judgment.\n- **Not yet handled:** return of capital, reinvested/notional distributions (ETF phantom distributions), stock splits, options, and other corporate actions. These affect ACB and are on the roadmap.\n- **FX** must be supplied per transaction (use the transaction-date rate). The tool does not fetch exchange rates.\n- Registered accounts (TFSA/RRSP) do not have capital gains; this tool is for **non-registered (taxable)** accounts.\n- **Not tax advice.**\n\n---\n\n## Development\n\n```bash\nuv venv\nuv pip install -e \".[dev]\"\nuv run pytest\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 7930,
  "sha": "191edba91b14e49a3a89535655be5b189e42b8d01bb51b7c07232977e3e34820",
  "repo_slug": "haiiibin/acb-tax-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_haiiibin_acb_tax_mcp_1912d863/readme"
}