Mercury Enhanced MCP

Mercury Enhanced MCP

A custom Model Context Protocol (MCP) server for the Mercury 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)
• Claude Desktop (or any MCP-compatible client)

---

Installation

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):

{
  "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. 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