# fidelity-mcp

> **DISCLAIMER: This project is not affiliated with, endorsed by, or associated with Fidelity Investments or FMR LLC. Use at your own risk. See [DISCLAIMER.md](DISCLAIMER.md) for full legal notice.**

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives Claude and other AI agents read/write access to your Fidelity Investments account via Playwright browser automation.

Fidelity does not offer a public API. This server works by capturing your authenticated browser session (via `fidelity_login.py`) and reusing it in a headless Playwright browser to read positions, balances, and transaction history — and to place orders.

## Features

| Tool | Description |
|------|-------------|
| `get_fidelity_balance` | Account balances and withdrawal availability |
| `get_fidelity_positions` | Open positions (ticker, quantity, price, value) |
| `get_fidelity_activity` | Recent transaction history (buys, sells, dividends) |
| `place_fidelity_stock_sell_limit` | Place a limit SELL order (Day or GTC) — dry-run by default |
| `check_fidelity_session` | Verify session file is present and populated |

## Requirements

- Python 3.11+
- Windows (Playwright's Firefox must run natively — WSL users see [WSL note](#wsl--claude-code) below)
- A Fidelity account

## Installation

```bash
pip install -r requirements.txt
playwright install firefox
```

## Quick Start

### Step 1 — Capture your session

Run the interactive login script. A Firefox window opens — log in normally (use your password manager, 2FA, etc.). When you reach the Fidelity dashboard, press ENTER in the terminal.

```bash
python fidelity_login.py
```

This saves `fidelity_session/Fidelity.json`. **Keep this file private — it grants access to your account. It is already in `.gitignore`.**

### Step 2 — Test the server

```bash
python fidelity_server.py
```

### Step 3 — Add to Claude Code

In your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "fidelity": {
      "command": "python",
      "args": ["path/to/fidelity_server.py"]
    }
  }
}
```

Then use it in Claude Code:

```
check_fidelity_session
get_fidelity_balance
get_fidelity_positions
get_fidelity_activity(days=7)

# Dry run first (default):
place_fidelity_stock_sell_limit(symbol="AAPL", quantity=10, limit_price=200, account="YOUR_ACCOUNT_NUMBER", dry_run=True)

# Execute for real:
place_fidelity_stock_sell_limit(symbol="AAPL", quantity=10, limit_price=200, account="YOUR_ACCOUNT_NUMBER", dry_run=False)
```

## WSL + Claude Code

If you run Claude Code on Windows but use WSL for MCP servers, Playwright's Firefox must run on the Windows side. Use a shell bridge:

**`launch.sh`** (place next to `fidelity_server.py`):
```bash
#!/bin/bash
exec cmd.exe /c "C:\\Python314\\python.exe C:\\path\\to\\fidelity_server.py"
```

**`.mcp.json`:**
```json
{
  "mcpServers": {
    "fidelity": {
      "command": "wsl.exe",
      "args": ["bash", "/mnt/c/path/to/launch.sh"]
    }
  }
}
```

## Session Expiry

Fidelity sessions typically last several hours to a day. When a tool returns:

```
No accounts found or session expired. Run fidelity_login.py to re-authenticate.
```

Re-run `fidelity_login.py` and restart the MCP server (or `/mcp restart` in Claude Code).

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `FIDELITY_SESSION_DIR` | `fidelity_session` | Directory for the session JSON file |

## Security

- `fidelity_session/` is in `.gitignore` — **never commit it**
- The session file is equivalent to being logged in — protect it like a password
- The server runs fully locally; no data is sent to any third party

## How it works

1. `fidelity_login.py` opens a real Firefox window using Playwright
2. You log in normally — Fidelity sees a real browser session
3. After login, `ctx.storage_state()` captures all cookies and localStorage to a JSON file
4. `fidelity_server.py` loads that state into a headless Firefox to reuse the session
5. Positions/balances use [fidelity-api](https://github.com/kennyboy106/fidelity-api) by kennyboy106
6. Activity scraping and order placement use direct Playwright page automation

## Dependencies

- [fidelity-api](https://github.com/kennyboy106/fidelity-api) by kennyboy106 — core account automation
- [playwright](https://playwright.dev/python/) — browser automation
- [playwright-stealth](https://github.com/AtuboDad/playwright_stealth) — reduces bot detection
- [mcp](https://github.com/modelcontextprotocol/python-sdk) — MCP server framework (FastMCP)

## License

MIT — see [LICENSE](LICENSE)

---

> **Not affiliated with Fidelity Investments. See [DISCLAIMER.md](DISCLAIMER.md).**