# Mercury Enhanced MCP

A custom Model Context Protocol (MCP) server for the [Mercury](https://mercury.com) banking API. Uses Mercury's personal API tokens instead of OAuth, eliminating the 3-day session expiry that breaks scheduled tasks.

> **Why not Mercury's official MCP?** Mercury's hosted MCP (`mcp.mercury.com`) uses OAuth2 Authorization Code flow with sessions that expire every 3 days — requiring manual re-authorization. Personal API tokens do not expire.

---

## Prerequisites

- Node.js 18 or later
- A Mercury personal API token ([generate one in Mercury Settings → API](https://app.mercury.com/settings/api))
- Claude Desktop (or any MCP-compatible client)

---

## Installation

```bash
git clone https://github.com/bradcollins/Mercury-Enhanced-MCP.git
cd Mercury-Enhanced-MCP
npm install
npm run build
```

---

## Configuration

### Claude Desktop

Add the following to your `claude_desktop_config.json` (usually at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "mercury-enhanced-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/Mercury-Enhanced-MCP/dist/index.js"],
      "env": {
        "MERCURY_API_TOKEN": "your_mercury_personal_api_token_here"
      }
    }
  }
}
```

Replace `/absolute/path/to/Mercury-Enhanced-MCP` with the actual path where you cloned this repo.

### Environment Variable

The server reads your token from `MERCURY_API_TOKEN`. Never commit this value to version control.

---

## Tools (15 total)

| Tool | Description |
|------|-------------|
| `get_accounts` | List all Mercury accounts (checking, savings) with balances and status |
| `get_account` | Get details of a specific account by ID |
| `get_account_cards` | List debit/credit cards associated with an account |
| `get_account_statements` | Get monthly statements for a checking/savings account |
| `get_transaction` | Get details of a single transaction by ID |
| `list_account_transactions` | List transactions for a specific account with date/status/search filters |
| `list_transactions` | Cross-account transaction search with advanced filters |
| `get_organization` | Get organization info (EIN, legal name, DBAs) |
| `get_recipients` | List all payment recipients |
| `get_recipient` | Get full details of a specific recipient by ID |
| `list_categories` | List all custom expense categories |
| `list_credit` | List all credit accounts |
| `get_treasury_accounts` | List all Mercury treasury accounts with balances and net returns |
| `get_treasury_transactions` | List transactions for a treasury account (integer cursor pagination) |
| `get_treasury_statements` | Get statements for a treasury account (MonthlyStatement, 1099, TradeConfirmation, etc.) |

---

## Usage Examples

Once configured in Claude Desktop, you can ask:

- "What are my Mercury account balances?"
- "Show me my last 10 transactions"
- "How much do I have in treasury?"
- "List all my payment recipients"
- "Show me all failed transactions this month"
- "What is my organization's legal business name?"
- "Download my treasury statements for last quarter"

---

## API Reference

This server wraps the [Mercury REST API v1](https://docs.mercury.com/reference). All requests use `Authorization: Bearer <token>`.

Key URL patterns:
- Single account: `/account/{id}` (singular)
- Single transaction: `/transaction/{id}` (singular)
- Treasury root: `/treasury`
- Treasury transactions: `/treasury/{id}/transactions`

---

## License

MIT — see [LICENSE](LICENSE)