Privat24 Business

Unofficial Model Context Protocol server for the Privat24 Business API.

This project exposes practical MCP tools for account statements, balances, transactions, payment creation, and exchange-rate lookups so an MCP-compatible client can work with Privat24 Business through structured tool calls instead of custom glue code.

This repository is not affiliated with, endorsed by, or maintained by PrivatBank.

What It Covers

• token-authenticated access to the Privat24 Business Autoclient API
• account and card discovery through statement settings
• balances and transactions for date ranges
• interim and final statement endpoints
• payment creation through the business API
• current and historical exchange-rate lookups through PrivatBank's public API
• a raw API tool for unsupported endpoints

Real Use Cases

• finance copilots that answer "show the balances for yesterday and flag accounts with low cash"
• treasury assistants that collect statement activity for a date range and summarize outgoing payments
• operations bots that fetch interim transactions during the day and compare them with final statements later
• internal accounting workflows that prepare payment drafts from natural-language requests and send them to /payment/create
• support or back-office agents that need a safe MCP layer instead of direct API scripting
• multi-tool automations that combine Privat24 Business data with ERP, CRM, BI, or reconciliation systems

Official References

• PrivatBank API developer portal: https://api.privatbank.ua/
• Privat24 Business integration overview: https://privatbank.ua/business/intehratsiya
• Autoclient API v3 documentation: https://docs.google.com/document/d/e/2PACX-1vTtKvGa3P4E-lDqLg3bHRF6Wi9S7GIjSMFEFxII5qQZBGxuTXs25hQNiUU1hMZQhOyx6BNvIZ1bVKSr/pub
• Autoclient instruction manual: https://docs.google.com/document/d/e/2PACX-1vTion-fu1RzMCQgZXOYKKWAmvi-QAAxZ7AKnAZESGY5lF2j3nX61RBsa5kXzpu7t5gacl6TgztonrIE/pub
• Public exchange rates API: https://api.privatbank.ua/#p24/exchange
• Model Context Protocol: https://modelcontextprotocol.io/introduction

Tools

• privat24_business_auth: verifies that the configured token can access the business API
• privat24_business_get_settings: returns statement settings, cards, and related metadata
• privat24_business_get_balances: returns balances from /statements/balance
• privat24_business_get_transactions: returns statement transactions from /statements
• privat24_business_get_interim_balances: returns data from /statements/interim/balance
• privat24_business_get_interim_transactions: returns data from /statements/interim/transactions
• privat24_business_get_final_balances: returns data from /statements/final/balance
• privat24_business_get_final_transactions: returns data from /statements/final/transactions
• privat24_business_create_payment: posts a JSON payment payload to /payment/create
• privat24_business_get_exchange_rates: returns current rates from the public PrivatBank API
• privat24_business_get_exchange_rate_history: returns historical rates for a DD.MM.YYYY date
• privat24_business_call_api: raw authenticated business API call for unsupported endpoints

Environment

Copy .env.example to .env and configure:

• PRIVAT24_BUSINESS_TOKEN: required token from Privat24 Business / Autoclient API access
• PRIVAT24_BUSINESS_BASE_URL: defaults to https://acp.privatbank.ua/api
• PRIVATBANK_PUBLIC_API_BASE_URL: defaults to https://api.privatbank.ua

Install

npm install

Run

npm run build
npm start

Development mode:

npm run dev

MCP Configuration Example

{
  "mcpServers": {
    "privat24-business": {
      "command": "node",
      "args": [
        "D:/usr/www/mcp-dev/privat24-business-mcp-server/dist/index.js"
      ],
      "env": {
        "PRIVAT24_BUSINESS_TOKEN": "your-token-here"
      }
    }
  }
}

Example Workflows

1. Verify access

Ask your MCP client:

Verify my Privat24 Business token and show the available statement settings.

The client should call privat24_business_auth or privat24_business_get_settings.

2. Summarize outgoing cash movement

Get transactions from 2026-03-01 to 2026-03-15 and summarize the largest outgoing payments.

The client should call privat24_business_get_transactions with:

{
  "from": "2026-03-01",
  "to": "2026-03-15"
}

3. Compare interim and final activity

Show the interim transactions for 2026-03-15, then compare them with the final transactions for the same day.

The client should call:

• privat24_business_get_interim_transactions
• privat24_business_get_final_transactions

4. Create a payment draft

Create a payment using this business API payload.

The client should call privat24_business_create_payment with a payload shaped to your Privat24 Business integration requirements.

Example:

{
  "payload": {
    "payerAccount": "26000000000000",
    "recipientAccount": "26000000000001",
    "recipientCode": "12345678",
    "recipientName": "Example LLC",
    "amount": 1500.25,
    "purpose": "Invoice 42"
  }
}

Use the official payment documentation above to adapt field names to your integration profile.

5. Reach an unsupported endpoint

Call the raw business API endpoint /some/custom/path with these query parameters.

The client should call privat24_business_call_api.

Notes

• The business API implementation in this repository assumes the documented Autoclient base URL https://acp.privatbank.ua/api.
• Current and historical FX tools use PrivatBank's public API, which does not require the business token.
• Payment payload requirements can vary by workflow. This server intentionally leaves the payload flexible and forwards your JSON as-is.
• If you need more endpoints, start with privat24_business_call_api, validate the request shape against the official docs, and then add a dedicated tool.

License

MIT