monobank-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Kutishevsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# Monobank MCP Server
+
+MCP (Model Context Protocol) server for integrating with Monobank API.
+
+## Prerequisites
+
+- Node.js 18.0.0 or higher
+- A Monobank API token. You can obtain it at: https://api.monobank.ua/
+
+**Note:** Your API token is only used locally and is never tracked or transmitted anywhere except to Monobank's API.
+
+## Available Tools
+
+The server provides three tools:
+
+1. **get_currency_rates** - Get currency exchange rates (rate limited to once per 5 minutes)
+2. **get_client_info** - Get client information and account details (rate limited to once per 60 seconds)
+3. **get_statement** - Get account statements for a specified date range (rate limited to once per 60 seconds, max 31 days + 1 hour)
+
+## MCP Configuration
+
+To use this server with an MCP client, add it to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "monobank": {
+      "command": "npx",
+      "args": ["monobank-mcp-server"],
+      "env": {
+        "MONOBANK_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+## Example Prompts
+
+### English
+- "Show me the current USD to UAH exchange rate"
+- "Get my account balance and recent transactions"
+- "Show me all transactions from the last week"
+- "What did I spend money on yesterday?"
+- "Show my statement for October 2024"
+- "Get all my credit card transactions from the last 3 days"
+
+### Українською
+- "Покажи поточний курс долара"
+- "Скільки грошей на моїх рахунках?"
+- "Покажи виписку за вчора"
+- "На що я витратив гроші цього тижня?"
+- "Покажи всі транзакції за жовтень"
+- "Скільки я витратив на їжу за останній місяць?"
+
+## License
+
+MIT

package/build/config.js

@@ -0,0 +1,17 @@
+let config = null;
+export function initializeConfig() {
+    if (!process.env.MONOBANK_API_TOKEN) {
+        throw new Error("Failed to get the MONOBANK_API_TOKEN. Probably it wasn't added during the server configuration.");
+    }
+    config = {
+        monobankApiToken: process.env.MONOBANK_API_TOKEN,
+        baseUrl: "https://api.monobank.ua",
+    };
+    return config;
+}
+export function getConfig() {
+    if (!config) {
+        throw new Error("Configuration not initialized. Call initializeConfig() first.");
+    }
+    return config;
+}

package/build/helpers.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export function createErrorResponse(message) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+    };
+}
+export function createSuccessResponse(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+export function formatZodError(error) {
+    return error.errors
+        .map((e) => `${e.path.join(".")}: ${e.message}`)
+        .join(", ");
+}
+export async function fetchWithErrorHandling(url, options) {
+    const response = await fetch(url, options);
+    if (!response.ok) {
+        const errorText = await response
+            .text()
+            .catch(() => response.statusText);
+        throw new Error(`HTTP ${response.status} - ${errorText}`);
+    }
+    return response;
+}
+export async function parseJsonResponse(response) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        throw new Error(`Failed to parse response as JSON: ${error instanceof Error ? error.message : "Unknown JSON error"}`);
+    }
+}
+export function formatErrorAsToolResponse(error, context) {
+    if (error instanceof z.ZodError) {
+        return createErrorResponse(`Invalid ${context} format: ${formatZodError(error)}`);
+    }
+    if (error instanceof Error) {
+        return createErrorResponse(error.message.startsWith("HTTP")
+            ? `Failed to ${context}: ${error.message}`
+            : `Error ${context}: ${error.message}`);
+    }
+    return createErrorResponse(`Error ${context}: Unknown error`);
+}
+export function validateStatementDates(from, to) {
+    const fromDate = new Date(from);
+    const toDate = to ? new Date(to) : new Date();
+    if (isNaN(fromDate.getTime())) {
+        return createErrorResponse(`Invalid 'from' date format: ${from}`);
+    }
+    if (to && isNaN(toDate.getTime())) {
+        return createErrorResponse(`Invalid 'to' date format: ${to}`);
+    }
+    const fromInSeconds = Math.floor(fromDate.getTime() / 1000);
+    const toInSeconds = Math.floor(toDate.getTime() / 1000);
+    // Validate time range (max 31 days + 1 hour = 2682000 seconds)
+    if (toInSeconds - fromInSeconds > 2682000) {
+        return createErrorResponse("Time range exceeds maximum allowed (31 days + 1 hour). Please use a smaller date range.");
+    }
+    return { fromInSeconds, toInSeconds };
+}
+export function formatStatementItems(items) {
+    return items.map((item) => ({
+        ...item,
+        amount: item.amount / 100,
+        operationAmount: item.operationAmount / 100,
+        cashbackAmount: item.cashbackAmount / 100,
+        balance: item.balance / 100,
+    }));
+}

package/build/index.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CurrencyRatesResponseSchema, StatementItemSchema } from "./schemas.js";
+import { createSuccessResponse, fetchWithErrorHandling, parseJsonResponse, formatErrorAsToolResponse, validateStatementDates, formatStatementItems, } from "./helpers.js";
+import { initializeConfig, getConfig } from "./config.js";
+const server = new McpServer({
+    name: "monobank-mcp-server",
+    version: "1.0.0",
+    capabilities: {
+        tools: {},
+    },
+});
+server.tool("get_currency_rates", "Get a basic list of currency rates from Monobank. The information can be refreshed once per 5 minutes, otherwise an error will be thrown.", {}, async () => {
+    try {
+        const { baseUrl } = getConfig();
+        const response = await fetchWithErrorHandling(`${baseUrl}/bank/currency`);
+        const result = await parseJsonResponse(response);
+        const currencyRates = CurrencyRatesResponseSchema.parse(result);
+        return createSuccessResponse(currencyRates);
+    }
+    catch (error) {
+        return formatErrorAsToolResponse(error, "get currency rates");
+    }
+});
+server.tool("get_client_info", "Get information about a client and a list of their accounts and jars. The tool can be called not more than 1 time per 60 seconds, otherwise an error will be thrown.", {}, async () => {
+    try {
+        const { baseUrl, monobankApiToken } = getConfig();
+        const response = await fetchWithErrorHandling(`${baseUrl}/personal/client-info`, {
+            headers: {
+                "X-Token": monobankApiToken,
+            },
+        });
+        const clientInfo = await parseJsonResponse(response);
+        return createSuccessResponse(clientInfo);
+    }
+    catch (error) {
+        return formatErrorAsToolResponse(error, "get client info");
+    }
+});
+server.tool("get_statement", "Get Monobank statement for the time from {from} to {to} time in seconds in Unix time format. The maximum time for which it is posssible to obtain a statement is 31 days + 1 hour (2682000 seconds). The statement can be retrieved not more than once per 60 seconds, otherwise an error will be thrown.", {
+    input: z.object({
+        account: z
+            .string()
+            .nonempty()
+            .describe("A unique indentificator of the Monobank account or a jar from the Statement list. If not provided, then a defaukt account is used, which is equal to '0'."),
+        from: z
+            .string()
+            .nonempty()
+            .describe("A date in ISO 8601 YYYY-MM-DD format."),
+        to: z
+            .string()
+            .optional()
+            .describe("A date in ISO 8601 YYYY-MM-DD format."),
+    }),
+}, async ({ input }) => {
+    try {
+        const { account, from, to } = input;
+        const dateValidation = validateStatementDates(from, to);
+        if ("content" in dateValidation) {
+            return dateValidation;
+        }
+        const { fromInSeconds, toInSeconds } = dateValidation;
+        const { baseUrl, monobankApiToken } = getConfig();
+        const response = await fetchWithErrorHandling(`${baseUrl}/personal/statement/${account}/${fromInSeconds}/${toInSeconds}`, {
+            headers: {
+                "X-Token": monobankApiToken,
+            },
+        });
+        const data = await parseJsonResponse(response);
+        const statement = z.array(StatementItemSchema).parse(data);
+        const formattedStatement = formatStatementItems(statement);
+        return createSuccessResponse(formattedStatement);
+    }
+    catch (error) {
+        return formatErrorAsToolResponse(error, "fetch statement");
+    }
+});
+async function main() {
+    initializeConfig();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Monobank MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/build/interfaces.js

@@ -0,0 +1 @@
+export {};

package/build/schemas.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export const CurrencyRateSchema = z.object({
+    currencyCodeA: z.number(),
+    currencyCodeB: z.number(),
+    date: z.number(),
+    rateBuy: z.number().optional(),
+    rateSell: z.number().optional(),
+    rateCross: z.number().optional(),
+});
+export const CurrencyRatesResponseSchema = z.array(CurrencyRateSchema);
+export const StatementItemSchema = z.object({
+    id: z.string(),
+    time: z.number(),
+    description: z.string(),
+    mcc: z.number(),
+    originalMcc: z.number(),
+    hold: z.boolean(),
+    amount: z.number().describe("Amount in cents, multiply by 100"),
+    operationAmount: z.number().describe("Amount in cents, multiply by 100"),
+    currencyCode: z.number(),
+    commissionRate: z.number(),
+    cashbackAmount: z.number().describe("Amount in cents, multiply by 100"),
+    balance: z.number().describe("Amount in cents, multiply by 100"),
+    comment: z.string().optional(),
+    receiptId: z.string().optional(),
+    invoiceId: z.string().optional(),
+    counterEdrpou: z.string().optional(),
+    counterIban: z.string().optional(),
+    counterName: z.string().optional(),
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "monobank-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Monobank API integration",
+  "main": "index.js",
+  "bin": {
+    "monobank-mcp-server": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x build/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [
+    "mcp",
+    "monobank",
+    "api",
+    "banking",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/akutishevsky/monobank-mcp-server.git"
+  },
+  "homepage": "https://github.com/akutishevsky/monobank-mcp-server#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "typescript": "^5.8.3"
+  }
+}