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)

Related MCP server: lunchmoney-mcp

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)

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