# Personal Capital MCP Connector

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects Claude to your **Empower / Personal Capital** financial data. Ask Claude natural-language questions about your accounts, net worth, spending, and investment holdings — all answered from live data.

## What it does

| Tool | Example questions |
|------|------------------|
| `list_accounts` | "What's my Chase credit card balance?" / "Show my savings accounts" |
| `get_net_worth` | "What's my net worth?" / "How much do I owe vs own?" |
| `get_transactions` | "What did I spend at restaurants last month?" |
| `get_asset_allocation` | "What's my asset allocation in my 401k?" |
| `check_auth_status` | "Is my Empower session still valid?" |

## Project structure

```
personal-capital-connector-mcp/
├── pyproject.toml
└── src/personal_capital_connector/
    ├── __init__.py
    ├── __main__.py
    ├── auth.py      # browser-based 2FA login + session persistence
    ├── client.py    # API wrapper and data formatters
    ├── server.py    # FastMCP server exposing 5 tools to Claude
    └── cli.py       # CLI entry point (auth / status / serve)
```

## Prerequisites

- [uv](https://docs.astral.sh/uv/) — fast Python package manager
- An [Empower / Personal Capital](https://empowerment.com/) account

## Setup

**Step 1 — Clone and authenticate (interactive browser + 2FA):**
```bash
git clone https://github.com/meetvanani/personal-capital-connector-mcp.git
cd personal-capital-connector-mcp
uv run personal-capital-connector auth
```
A browser window opens, auto-fills your credentials, and waits for you to complete 2FA. The session is saved to `~/.config/personal-capital-connector/session.json` (chmod 600). Re-run this any time your session expires.

**Step 2 — Add to Claude Desktop's MCP config:**

Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add:

```json
{
  "mcpServers": {
    "personal-capital": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/personal-capital-connector-mcp",
        "personal-capital-connector"
      ]
    }
  }
}
```

Replace `/absolute/path/to/personal-capital-connector-mcp` with the actual path where you cloned the repo.

**Step 3 — Restart Claude Desktop** and start asking questions.

## Other CLI commands

```bash
# Check if the saved session is still valid
uv run personal-capital-connector status

# Explicitly start the MCP server (same as default / no subcommand)
uv run personal-capital-connector serve
```

## How authentication works

Login uses [Playwright](https://playwright.dev/) to open a real Chromium browser:
1. Auto-fills your email and password
2. Waits up to 3 minutes for you to complete 2FA (SMS, email, or authenticator app)
3. Detects successful authentication by intercepting the first valid API response from Empower
4. Extracts and saves the session cookies + CSRF token to disk

This approach handles Empower's frequent login-flow changes without brittle scraping.