Monobank MCP Server

monobank-mcp

适用于 Monobank 的 MCP 服务——将您的账户、交易、汇率和 Webhook 配置作为工具提供给 Claude 和其他 MCP 客户端。

响应经过预处理，便于大模型使用：金额以基础货币单位表示（而非分），时间戳采用 ISO 8601 格式，货币代码为 ISO 4217 字符串，权限会解码为易读名称。经常访问的数据会在服务端缓存 1 小时，因此重复读取不会触及 Monobank 的速率限制。

快速开始——Claude Desktop

将以下内容添加到您的 claude_desktop_config.json：

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

快速开始——Claude Code

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

然后将您的令牌添加到 .claude/settings.json：

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

获取令牌

打开 api.monobank.ua，使用 Monobank 应用扫描二维码以生成您的个人 API 令牌。令牌不会离开您的计算机——它会作为环境变量直接传递给服务进程。

可用工具

公共工具——无需令牌

工具	描述
monobank-bank-currency	所有 Monobank 汇率。返回 baseCurrency / quoteCurrency（ISO 4217）、date（ISO 8601），以及 rateSell / rateBuy（交易货币对）或 rateCross（交叉汇率）。
monobank-bank-currency-rate	单个货币对的汇率。输入：baseCurrency、quoteCurrency（默认为 UAH）。比获取完整列表更快。

个人 — 需要 MONOBANK_API_TOKEN

工具	描述
monobank-personal-client-info	完整的客户资料：身份信息、解码后的令牌权限、所有账户和存钱罐，包括 FOP／企业账户（managedClients）。账户的 id 字段可用于调用账单工具。
monobank-personal-accounts	简明的账户和存钱罐列表（id、type、currencyCode、balance、maskedPan）。获取账单前，可使用此工具快速查找账户。
monobank-personal-statement	账户交易记录。输入：accountId（来自 client-info，或使用 "0" 表示默认 UAH 账户）、fromDate、toDate（带时区的 ISO 8601 格式）。每次请求的最大时间范围：31 天。
monobank-get-webhook	返回当前为此令牌配置的 webhook URL。空字符串表示尚未设置 webhook。
monobank-set-webhook	⚠️ 有破坏性。 设置 webhook URL。会立即覆盖现有 URL，不会进行确认——请先使用 monobank-get-webhook 检查当前值。
monobank-unset-webhook	⚠️ 有破坏性。 将 URL 设为空字符串，以移除 webhook。

缓存

服务会缓存响应，以遵守 Monobank 的速率限制并避免重复的 API 调用：

数据	缓存 TTL
客户信息（/personal/client-info）	1 小时
货币汇率（/bank/currency）	1 小时
设置了固定 toDate 的账单	1 小时
未设置 toDate 的账单	不缓存（范围开放，存在数据过期风险）

Webhook 变更会自动使客户信息缓存失效，因此下一次读取将反映更新后的 URL。

速率限制

Monobank 个人端点每 60 秒允许 1 次请求。如果达到限制，服务会返回清晰的错误消息，提示你等待 60 秒。由于缓存时长为 1 小时，大多数重复读取都会从本地缓存提供，完全不会调用 API。

开发者设置

需要 Node.js ≥ 24.17.0 和 pnpm。

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

创建 .env 文件：

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/

故障排除

令牌无效／401 — 在 api.monobank.ua 重新生成令牌。令牌在未使用时会过期。

速率限制／429 — 等待 60 秒。发生这种情况时，服务会告知你。在一小时内重复读取会从缓存中提供，不会触发此限制。

账单范围超过 31 天 — 将请求拆分为多次调用，每次覆盖不超过 31 天。如果范围过宽，工具会提示你。

未找到货币对 — 使用 monobank-bank-currency 查看所有可用货币对。仅支持 UAH 货币对以及 EUR/USD。

client-info 中没有 managedClients — 只有在 Monobank 注册为 FOP（个体经营者）时才会出现此字段。所有令牌都是相同的个人令牌——如果你没有 FOP 账户，managedClients 字段就不会出现。

许可证

MIT