@jbctechsolutions/mcp-mercury

License: MIT

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:

MERCURY_API_TOKEN environment variable — intended for tests/CI only
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/