# sophtron-mcp

MCP server for [Sophtron](https://sophtron.com/) — connect bank accounts and retrieve financial data (accounts, balances, transactions) through the Model Context Protocol.

Sophtron is a financial data aggregation platform. This server wraps the Sophtron API and exposes it as a set of MCP tools that Claude (or any MCP client) can use to search for banks, connect accounts with credential and MFA handling, list accounts, and pull transaction history.

## Tools

| Tool | Description |
|------|-------------|
| `connect_bank` | Launch an interactive wizard to connect a new bank or credit card account (UI-based) |
| `manage_accounts` | Open the account management UI to select, rename, and organize linked bank accounts (UI-based) |
| `search_institutions` | Search for banks and financial institutions by name |
| `create_connection` | Create a new bank connection with login credentials; returns a job ID for polling |
| `poll_job` | Check the status of a connection or refresh job; poll every 4-5 seconds until complete |
| `answer_mfa` | Submit an MFA response (security question, verification code, token choice, phone verification, or captcha) |
| `get_connection_accounts` | List accounts for a specific bank connection |
| `save_account_preferences` | Save account selection and custom names after connecting a bank |
| `get_account_preferences` | Read stored account preferences (selection, custom names) for a connection |
| `rename_account` | Set or clear a custom display name for a bank account |
| `toggle_account` | Show or hide a bank account from the active list |
| `list_connections` | List all linked bank connections for this account |
| `list_accounts` | List accounts for a bank connection (selected accounts only by default) |
| `get_transactions` | Get transactions for a bank account (defaults to last 90 days) |
| `refresh_account` | Trigger a fresh data pull from the bank for a specific account; returns a job ID to poll |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SOPHTRON_USER_ID` | Yes | Your Sophtron API user ID |
| `SOPHTRON_ACCESS_KEY` | Yes | Your Sophtron API access key (secret) |
| `SOPHTRON_API_ENDPOINT` | No | API base URL (defaults to `https://api.sophtron.com/api`) |
| `SOPHTRON_CUSTOMER_NAME` | No | Customer name override |

## Installation

```bash
npm ci
```

## Usage

### stdio mode (for MCP clients like Claude Desktop)

```bash
SOPHTRON_USER_ID=your-id SOPHTRON_ACCESS_KEY=your-key node dist/index.js
```

### Claude Desktop configuration

Add to your Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "sophtron": {
      "command": "node",
      "args": ["/path/to/sophtron-mcp/dist/index.js"],
      "env": {
        "SOPHTRON_USER_ID": "your-id",
        "SOPHTRON_ACCESS_KEY": "your-key"
      }
    }
  }
}
```

### HTTP mode (with mcp-proxy)

```bash
mcp-proxy --port 8001 -- node dist/index.js
```

## Data Storage

Account preferences (custom names, selected/hidden status) are stored locally in `~/.sophtron-mcp/connections.json`. No bank credentials are stored locally.

## License

MIT