# @striderlabs/mcp-usaa

[![npm version](https://img.shields.io/npm/v/@striderlabs/mcp-usaa.svg)](https://www.npmjs.com/package/@striderlabs/mcp-usaa)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**USAA banking and insurance connector for personal AI agents.**

Enables AI assistants to manage your USAA accounts — check balances, view transactions, transfer funds, pay bills, manage insurance policies, file claims, access investments, and more — all through the Model Context Protocol.

## Features

- **Banking** — Account balances, transaction history, fund transfers, bill pay, mobile check deposit
- **Insurance** — View policies (auto, home, renters, life), file claims, track claim status
- **Investments** — Brokerage, IRA, and 529 account access with holdings
- **Credit Cards** — Balances, available credit, payment info, transaction history
- **Loans** — Auto, personal, mortgage, and VA loan balances and payment details
- **Session Persistence** — Login once, sessions saved to `~/.strider/usaa/`

## Installation

```bash
npm install -g @striderlabs/mcp-usaa
```

Install the browser (required for automation):

```bash
npx patchright install chromium
```

## MCP Client Configuration

### Claude Desktop

Add to your `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "usaa": {
      "command": "striderlabs-mcp-usaa"
    }
  }
}
```

### Other MCP Clients

```json
{
  "mcpServers": {
    "usaa": {
      "command": "npx",
      "args": ["-y", "@striderlabs/mcp-usaa"]
    }
  }
}
```

## Available Tools

### Authentication

| Tool | Description |
|------|-------------|
| `usaa_status` | Check current login status |
| `usaa_login` | Open browser to USAA login page |
| `usaa_confirm_login` | Save session after manual login |
| `usaa_logout` | Clear session and log out |

### Banking

| Tool | Description |
|------|-------------|
| `usaa_get_account_balances` | All account balances (checking, savings, money market) |
| `usaa_get_transactions` | Transaction history for an account |
| `usaa_transfer_funds` | Transfer between accounts (requires `confirm=true`) |
| `usaa_pay_bill` | Pay a bill via Bill Pay (requires `confirm=true`) |
| `usaa_mobile_deposit` | Deposit a check image (requires `confirm=true`) |

### Insurance

| Tool | Description |
|------|-------------|
| `usaa_get_insurance_policies` | All policies (auto, home, renters, life, etc.) |
| `usaa_file_claim` | File a new insurance claim (requires `confirm=true`) |
| `usaa_get_claim_status` | Status of existing claims |

### Investments

| Tool | Description |
|------|-------------|
| `usaa_get_investment_accounts` | Brokerage, IRA, 529 accounts with holdings |

### Credit Cards

| Tool | Description |
|------|-------------|
| `usaa_get_credit_cards` | All cards with balances and payment info |
| `usaa_get_credit_card_transactions` | Transaction history for a card |

### Loans

| Tool | Description |
|------|-------------|
| `usaa_get_loans` | All loans with balances and payment details |

## Usage Examples

### Check balances
```
"What are my USAA account balances?"
→ calls usaa_get_account_balances
```

### Transfer money
```
"Transfer $500 from my checking to savings"
→ calls usaa_transfer_funds with confirm=true
```

### File a claim
```
"File an auto insurance claim for a fender bender on March 10th"
→ calls usaa_file_claim with confirm=true
```

### Check investments
```
"How are my USAA investments doing?"
→ calls usaa_get_investment_accounts
```

## Authentication Flow

USAA uses multi-factor authentication, so login is browser-assisted:

1. Call `usaa_login` — a browser window opens to USAA's login page
2. Complete login manually in the browser (username, password, MFA code)
3. Call `usaa_confirm_login` — session cookies are saved to `~/.strider/usaa/`
4. All subsequent calls use the saved session automatically

Sessions persist until they expire or you call `usaa_logout`.

## Safety & Confirmation

Destructive or financial operations require explicit confirmation:

- `usaa_transfer_funds` — requires `confirm: true`
- `usaa_pay_bill` — requires `confirm: true`
- `usaa_mobile_deposit` — requires `confirm: true`
- `usaa_file_claim` — requires `confirm: true`

Calling without `confirm: true` returns a preview of the action without executing it.

## Technical Details

- Built on [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (stealth Playwright fork) for browser automation
- Runs headful Chrome to handle USAA's bot detection and MFA
- Session data stored in `~/.strider/usaa/` (auth.json + session.json)
- Communicates with MCP clients via stdio transport

## Limitations

- **Manual login required** — USAA's security requires human-in-the-loop for initial authentication
- **MFA required** — Must complete MFA in the browser window during login
- **Session expiry** — USAA sessions expire; re-login will be needed periodically
- **DOM-dependent** — Selectors may need updates if USAA changes their web UI

## Troubleshooting

**"Not logged in" errors**
→ Call `usaa_login`, complete login in the browser, then `usaa_confirm_login`

**"Timeout" errors**
→ USAA's site may be slow or your session expired. Try re-logging in.

**"net::ERR_" errors**
→ Check your internet connection. USAA may be temporarily unavailable.

**Browser doesn't open**
→ Run `npx patchright install chromium` to install the browser

## Development

```bash
git clone https://github.com/striderlabs/mcp-usaa
cd mcp-usaa
npm install
npm run build
npm start
```

## License

MIT — See [LICENSE](LICENSE)

---

By [Strider Labs](https://striderlabs.ai) · [Report Issues](https://github.com/striderlabs/mcp-usaa/issues)