# taxfolio-mcp

MCP server for [taxfolio](https://github.com/ajtgjmdjp/taxfolio) — tax-loss harvesting via LLM agents.

## Tools

### `harvest_losses`

Find tax-loss harvesting opportunities. Sells losers, buys same-industry substitutes ranked by return correlation.

**Input:**
```json
{
  "holdings": [
    {"ticker": "INTC", "shares": 200, "cost_basis": 45.0, "acquired": "2024-06-01"},
    {"ticker": "NVDA", "shares": 50, "cost_basis": 130.0, "acquired": "2024-06-01"}
  ],
  "min_loss_pct": 5.0,
  "min_correlation": 0.5
}
```

**Output:**
```json
{
  "summary": {"positions_harvested": 1, "total_loss_harvested": -4600.0, "total_tax_benefit": 1702.0},
  "trades": [{"sell_ticker": "INTC", "sell_shares": 200, "buy_ticker": "MU", "correlation": 0.48}],
  "warnings": [],
  "limitations": ["Market data from yfinance", "Not tax advice"]
}
```

### `optimize`

Tax-aware portfolio rebalancing via C++20 QP solver.

## Install

```bash
# Requires taxfolio to be installed first
# See: https://github.com/ajtgjmdjp/taxfolio
uv pip install taxfolio-mcp
```

## Usage with Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "taxfolio": {
      "command": "taxfolio-mcp"
    }
  }
}
```

Then ask Claude:

> "Find tax-loss harvesting opportunities in my portfolio: INTC 200 shares bought at $45, NVDA 50 shares bought at $130, PFE 300 shares bought at $35"

## Limitations

- Market data fetched via yfinance (may be delayed or unavailable)
- Substitute matching is heuristic (industry group + return correlation)
- Maximum 100 holdings per request
- **Not tax advice** — consult a tax professional before executing trades

## License

[AGPL-3.0](LICENSE)