@jbctechsolutions/mcp-mercury

Read-only MCP server for Mercury business banking — accounts, transactions, and statements.

A Model Context Protocol (MCP) server that exposes 6 read-only tools against the Mercury API. No payment, recipient, or any other write endpoint is implemented, by design.

Tools

| Tool | Description | |------|-------------| | list_accounts | All accounts with balances, account/routing numbers, status | | get_account | One account by ID | | list_transactions | Transactions for an account (date range, status, search, pagination) | | get_transaction | One transaction by ID | | list_statements | Monthly statements (period, ending balance, PDF download URL) | | download_statement_pdf | Save a statement PDF to a local path (mercury.com URLs only) |

Token handling

The Mercury API token is resolved at runtime, in this order:

1. MERCURY_API_TOKEN environment variable — intended for tests/CI only
2. 1Password CLI: op item get "Mercury API - read only" --account jbctechsolutions.1password.com --fields label=credential --reveal

The token is cached in memory only. It is never written to disk, never logged, and never included in error messages. Statement downloads refuse non-mercury.com URLs so the bearer token cannot be sent elsewhere.

Create the token in Mercury with read-only scope (Settings → API Tokens), store it in the 1Password item's credential field, and you're done — no config files.

Environment overrides

| Variable | Default | Purpose | |----------|---------|---------| | MERCURY_API_TOKEN | — | Bypass 1Password (tests/CI) | | MERCURY_OP_ACCOUNT | jbctechsolutions.1password.com | 1Password account | | MERCURY_OP_ITEM | Mercury API - read only | 1Password item name | | MERCURY_API_BASE_URL | https://api.mercury.com/api/v1 | API base (tests only) |

Quick start

npm install
npm run build

Claude Code / Claude Desktop configuration

{
  "mcpServers": {
    "mercury": {
      "command": "node",
      "args": ["/path/to/mcp-mercury/dist/index.js"]
    }
  }
}

(Once published: npx -y @jbctechsolutions/mcp-mercury.)

The 1Password CLI must be installed and signed in to the jbctechsolutions account for token resolution to work.

Development

npm test          # vitest unit tests
npm run typecheck # tsc --noEmit
npm run build     # compile to dist/

License

MIT © JBC Tech Solutions, LLC