Monobank MCP Server

Instructions

Implementation Reference

• src/index.ts:127-201 (handler)

  The main handler function for the 'get_statement' tool. It validates input using GetStatementArgsSchema, fetches the statement from the Monobank API, processes the data (converting timestamps and amounts), and returns a formatted JSON response.
  async function getStatement(args: unknown) { /** * Get account statement for a given period. * Rate limit: 1 request per 60 seconds. * Max period: 31 days + 1 hour. * * Rules: * 1. Fetch from default account (account_id = "0") unless another account is specified. * 2. Amounts are converted from the smallest currency unit (e.g., kopiyka, cent) * to the main unit and returned as decimals. * 3. Transaction timestamps ("time") are converted from Unix timestamps to * ISO 8601 datetime strings (UTC). * 4. Fields "id", "invoiceId", "counterEdrpou", and "counterIban" are omitted * from the returned results. */ const parsed = GetStatementArgsSchema.parse(args); const { account_id, from_timestamp, to_timestamp } = parsed; const finalToTimestamp = to_timestamp || Math.floor(Date.now() / 1000); try { const response = await fetch( `https://api.monobank.ua/personal/statement/${account_id}/${from_timestamp}/${finalToTimestamp}`, { headers: { "X-Token": process.env.MONOBANK_API_TOKEN || "X_TOKEN_PLACEHOLDER", }, } ); if (!response.ok) { const errorText = await response.text(); throw new Error(`HTTP error! status: ${response.status}, body: ${errorText}`); } const data: StatementItem[] = await response.json() as StatementItem[]; const processedItems: ProcessedStatementItem[] = data.map((item) => { const time = new Date(item.time * 1000).toISOString(); const processedItem: ProcessedStatementItem = { time, description: item.description, mcc: item.mcc, originalMcc: item.originalMcc, hold: item.hold, amount: item.amount / 100, operationAmount: item.operationAmount / 100, currencyCode: item.currencyCode, commissionRate: item.commissionRate / 100, cashbackAmount: item.cashbackAmount / 100, balance: item.balance / 100, comment: item.comment, receiptId: item.receiptId, counterName: item.counterName, }; return processedItem; }); return { content: [ { type: "text", text: JSON.stringify(processedItems, null, 2), }, ], }; } catch (error) { if (error instanceof Error) { throw new Error(`Failed to connect to Monobank API: ${error.message}`); } throw new Error(`Failed to connect to Monobank API: ${String(error)}`); } }
• src/index.ts:83-87 (schema)

  Zod schema defining the input parameters for the get_statement tool, used for validation within the handler.
  const GetStatementArgsSchema = z.object({ account_id: z.string().describe("Account identifier from the list of accounts, or '0' for default"), from_timestamp: z.number().describe("Start of the statement period (Unix timestamp)"), to_timestamp: z.number().describe("End of the statement period (Unix timestamp)"), });
• src/index.ts:227-248 (registration)

  Tool registration in the ListTools response, including name, description, and input schema definition.
  { name: "get_statement", description: "Get account statement for a given period. Rate limit: 1 request per 60 seconds. Max period: 31 days + 1 hour. Rules: 1. Fetch from default account (account_id = '0') unless another account is specified. 2. Amounts are converted from the smallest currency unit (e.g., kopiyka, cent) to the main unit and returned as decimals. 3. Transaction timestamps ('time') are converted from Unix timestamps to ISO 8601 datetime strings (UTC). 4. Fields 'id', 'invoiceId', 'counterEdrpou', and 'counterIban' are omitted from the returned results.", inputSchema: { type: "object", properties: { account_id: { type: "string", description: "Account identifier from the list of accounts, or '0' for default", }, from_timestamp: { type: "number", description: "Start of the statement period (Unix timestamp)", }, to_timestamp: { type: "number", description: "End of the statement period (Unix timestamp)", }, }, required: ["account_id", "from_timestamp", "to_timestamp"], }, },
• src/index.ts:256-257 (registration)

  Dispatch case in the CallToolRequest handler that routes requests for 'get_statement' to the getStatement function.
  case "get_statement": return await getStatement(request.params.arguments);
• src/index.ts:65-81 (schema)

  TypeScript interface for the processed statement items returned by the handler, excluding certain fields and with transformed types.
  interface ProcessedStatementItem { time: string; description: string; mcc: number; originalMcc: number; hold: boolean; amount: number; operationAmount: number; currencyCode: number; commissionRate: number; cashbackAmount: number; balance: number; comment?: string; receiptId?: string; counterName?: string; }