Mercury Enhanced

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