# Capitol Trades MCP

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that surfaces **US congressional stock-trade disclosures** from [capitoltrades.com](https://www.capitoltrades.com) — **no API key required**.

It exposes 23 tools for querying, filtering, ranking, and exporting politician trades, built on [FastMCP](https://github.com/jlowin/fastmcp).

> ⚠️ **Not investment advice.** This server reports publicly disclosed transactions for research and transparency only.

## How it works

capitoltrades.com is a Next.js (App Router) site on Vercel. Instead of scraping presentational HTML — which breaks on every redesign — this server reads the structured trade records embedded in the page's React Server Component **flight stream** (`self.__next_f.push(...)` script chunks), where each trade is a clean JSON object. That keeps the parser resilient to cosmetic changes and exposes richer fields than the rendered table: per-share `price`, `reportingGap`, estimated `value`, `owner`, `sector`, `comment`, and stable ids.

## Tools

**Core**
- `get_politician_trades` — filtered trade list (issuer, politician, party, type, window)
- `get_top_traded_assets` — most-traded assets, ranked by trade count
- `get_politician_stats` — per-politician breakdown
- `get_asset_stats` — per-asset breakdown
- `get_buy_momentum_assets` — assets where politicians are net buyers
- `get_party_buy_momentum` — net buyers split into consensus / Democrat / Republican

**Feeds & lookups**
- `get_recent_trades` — latest disclosures across all politicians
- `search_politicians` — resolve a name to its Capitol Trades id (+ party/state/stats)
- `search_issuers` — resolve a ticker/name to issuer id, sector and stats
- `get_trade_detail` — full record for a single transaction id

**Filter dimensions**
- `get_trades_by_sector` · `get_trades_by_state` · `get_trades_by_owner` · `get_trades_by_chamber`

**Rankings & analytics**
- `get_largest_trades` — biggest trades by estimated value
- `get_most_active_politicians` — ranked by trade count then value
- `get_sector_momentum` — net buy/sell flow by sector
- `get_politician_net_positions` — per-asset net buying/selling for one member

**Compliance / disclosure quality**
- `get_late_filings` — trades disclosed slower than the STOCK Act's 45-day window
- `get_disclosure_gap_leaderboard` — members ranked by average reporting gap

**Cross-referencing**
- `get_congress_activity_for_tickers` — batch summary for a watchlist of tickers

**Output / convenience**
- `export_trades_csv` — filtered trades as CSV text
- `get_trades_in_date_range` — trades within an arbitrary `YYYY-MM-DD` range

## Requirements

- Python 3.10+
- `fastmcp`, `httpx`, `beautifulsoup4`, `lxml`

## Installation

```bash
git clone https://github.com/jsconiers/capitol-trades-mcp.git
cd capitol-trades-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

> 🍏 **Apple Silicon note:** install with the virtual-env's own `pip` (as above), **not** a Rosetta/x86_64 `uv` — otherwise native wheels such as `pydantic-core` can fail to load with an "incompatible architecture" error.

It also runs dependency-free via [`uv`](https://github.com/astral-sh/uv) thanks to inline [PEP 723](https://peps.python.org/pep-0723/) metadata:

```bash
uv run capital_trades_mcp.py
```

## Claude Desktop configuration

Add to `claude_desktop_config.json` (see `claude_desktop_config.example.json`), using **absolute** paths:

```json
{
  "mcpServers": {
    "capitol-trades": {
      "command": "/absolute/path/to/capitol-trades-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/capitol-trades-mcp/capital_trades_mcp.py"],
      "env": {}
    }
  }
}
```

Restart Claude Desktop. No API key or credentials are required.

## Usage examples

- "What are the most recent congressional trades?" → `get_recent_trades`
- "Show me Nancy Pelosi's trades over the last year." → `get_politician_stats`
- "Who in Congress has been buying NVDA?" → `get_asset_stats`
- "Which members filed late this quarter?" → `get_late_filings`
- "Cross-reference my watchlist [AAPL, MSFT, NVDA] against Congress." → `get_congress_activity_for_tickers`

## Testing

```bash
python test_port.py
```

Offline tests cover the flight-JSON parser, the issuer/politician parsers, every aggregation/filter helper, CSV export, and tool registration. No network needed.

## Notes & limitations

- **Filtering windows:** filter/ranking tools pull up to ~500 of the most recent trades in the look-back window and filter client-side, so very rare sectors/states may be under-represented over long windows.
- **Window cache:** repeated analytics on the same look-back window share one fetch for ~60 seconds.
- **`N/A` tickers:** some disclosed issuers (private funds, certain instruments) carry no ticker in the source data.
- **Be courteous:** the server delays slightly between paginated requests. Respect capitoltrades.com's terms of service.

## Credits

- Data: [Capitol Trades](https://www.capitoltrades.com) (2iQ Research).
- Python/FastMCP port inspired by the Node/TypeScript project [`anguslin/mcp-capitol-trades`](https://github.com/anguslin/mcp-capitol-trades). **Review the upstream project's license before redistributing.**

## License

MIT for this Python port — see [`LICENSE`](LICENSE). Capitol Trades data and the upstream project remain under their respective terms.