monobank-mcp

MCP server for Monobank — exposes your accounts, transactions, exchange rates, and webhook configuration as tools for Claude and other MCP clients.

Responses are pre-processed for LLM consumption: amounts are in base currency units (not cents), timestamps are ISO 8601, currency codes are ISO 4217 strings, and permissions are decoded to human-readable names. Frequently-accessed data is cached server-side for 1 hour so repeated reads never hit the Monobank rate limit.

Quick Start — Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "monobank": {
      "command": "npx",
      "args": ["-y", "@dirgen/monobank-mcp"],
      "env": {
        "MONOBANK_API_TOKEN": "your_token_here"
      }
    }
  }
}

Quick Start — Claude Code

claude mcp add monobank -- npx -y @dirgen/monobank-mcp

Then add your token to .claude/settings.json:

{
  "mcpServers": {
    "monobank": {
      "env": { "MONOBANK_API_TOKEN": "your_token_here" }
    }
  }
}

Getting a Token

Open api.monobank.ua and scan the QR code with the Monobank app to generate your personal API token. The token never leaves your machine — it is passed directly to the server process as an environment variable.

Available Tools

Public — no token required

| Tool | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | monobank-bank-currency | All Monobank exchange rates. Returns baseCurrency / quoteCurrency (ISO 4217), date (ISO 8601), and rateSell / rateBuy (traded pairs) or rateCross (cross rates). | | monobank-bank-currency-rate | Exchange rate for a single currency pair. Inputs: baseCurrency, quoteCurrency (defaults to UAH). Faster than fetching the full list. |

Personal — requires MONOBANK_API_TOKEN

| Tool | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | monobank-personal-client-info | Full client profile: identity, decoded token permissions, all accounts and jars including FOP/business accounts (managedClients). Account id fields are what you pass to the statement tool. | | monobank-personal-accounts | Compact account and jar list (id, type, currencyCode, balance, maskedPan). Use this for quick account discovery before fetching statements. | | monobank-personal-statement | Transaction history for an account. Inputs: accountId (from client-info, or "0" for default UAH account), fromDate, toDate (ISO 8601 with timezone). Maximum range: 31 days per request. | | monobank-get-webhook | Returns the webhook URL currently configured for this token. Empty string means no webhook is set. | | monobank-set-webhook | ⚠️ Destructive. Sets the webhook URL. Overwrites the existing URL immediately with no confirmation — check the current value with monobank-get-webhook first. | | monobank-unset-webhook | ⚠️ Destructive. Removes the webhook by setting the URL to empty string. |

Caching

The server caches responses to stay within Monobank's rate limits and avoid redundant API calls:

| Data | Cache TTL | | ------------------------------------- | ----------------------------------------------- | | Client info (/personal/client-info) | 1 hour | | Currency rates (/bank/currency) | 1 hour | | Statement with a fixed toDate | 1 hour | | Statement without toDate | Not cached (open-ended range → stale data risk) |

Webhook mutations automatically invalidate the client-info cache so the next read reflects the updated URL.

Rate Limits

Monobank personal endpoints allow 1 request per 60 seconds. If the limit is hit, the server returns a clear error message telling you to wait 60 seconds. The 1-hour cache means most repeated reads are served locally without hitting the API at all.

Developer Setup

Requires Node.js ≥ 24.17.0 and pnpm.

git clone https://github.com/dirgen/monobank-mcp
cd monobank-mcp
pnpm install

Create a .env file:

MONOBANK_API_TOKEN=your_token_here

pnpm start       # run the MCP server
pnpm inspect     # open MCP Inspector in the browser for interactive testing
pnpm typecheck   # type-check without emitting
pnpm lint        # lint src/

Troubleshooting

Invalid token / 401 — regenerate your token at api.monobank.ua. Tokens expire if unused.

Rate limit / 429 — wait 60 seconds. The server will tell you when this happens. Repeated reads within an hour are served from cache and won't trigger this.

Statement range > 31 days — split the request into multiple calls, each covering ≤ 31 days. The tool will tell you if the range is too wide.

Currency pair not found — use monobank-bank-currency to see all available pairs. Only UAH pairs and EUR/USD are available.

No managedClients in client-info — this field only appears if you are registered as a FOP (sole proprietor) with Monobank. All tokens are the same personal token — managedClients is simply absent if you have no FOP accounts.

License

MIT