# @jbctechsolutions/mcp-mercury

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Read-only MCP server for [Mercury](https://mercury.com) business banking — accounts, transactions, and statements.

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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

```bash
npm install
npm run build
```

### Claude Code / Claude Desktop configuration

```json
{
  "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

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

## License

MIT © JBC Tech Solutions, LLC