Skip to main content
Glama

ua-mcp

An MCP server for three Ukrainian services: Nova Poshta, Ukrposhta and Monobank. Seven tools, all read-only, each built around a question a person asks rather than around an API method.

"Скільки коштує відправити 2 кг з Києва до Одеси?"   → np_quote
"Де посилка 0500100031143?"                           → ukrposhta_track
"Скільки я витратив у Сільпо за листопад?"            → mono_statement

Tools

Tool

Answers

Needs

np_track

Where a Nova Poshta parcel is, when it is expected, whether it was picked up. Up to 20 numbers.

nothing

np_find_branch

Branches and parcel lockers in a city: address, hours, weight limit, working or not.

nothing

np_quote

Delivery cost and arrival date between two cities, from city names.

nothing

ukrposhta_track

Status and full route of a Ukrposhta shipment.

UKRPOSHTA_TRACKING_BEARER

mono_rates

Monobank buy and sell rates against the hryvnia.

nothing

mono_accounts

Cards, accounts and jars with balances.

MONOBANK_TOKEN

mono_statement

Operations for up to 31 days with totals, optionally filtered by text.

MONOBANK_TOKEN

A tool is registered only when it can work. With no credentials the server offers four tools; the other three appear when their token is set. The model never sees a tool it cannot use.

Related MCP server: moysklad-analytics-mcp

Run it

npm install
npm run build

.mcp.json for Claude Code, or the same block in any MCP client:

{
  "mcpServers": {
    "ua": {
      "command": "node",
      "args": ["/path/to/ua-mcp/dist/index.js"],
      "env": {
        "NOVA_POSHTA_API_KEY": "",
        "UKRPOSHTA_TRACKING_BEARER": "",
        "MONOBANK_TOKEN": ""
      }
    }
  }
}

Variable

Where it comes from

NOVA_POSHTA_API_KEY

Optional. The business cabinet at new.novaposhta.ua. The three tools work without it.

UKRPOSHTA_TRACKING_BEARER

The status-tracking bearer from the annex to an agreement with Ukrposhta.

MONOBANK_TOKEN

A personal token from api.monobank.ua. It reads your own accounts, so treat it as a password.

Decisions

  • Read-only. Nothing here creates a waybill or moves money. Every tool carries readOnlyHint, so a client can run them without asking each time. Writes belong in a separate server with its own confirmation step.

  • Questions, not endpoints. np_quote takes "Київ" and "Одеса", resolves both to the carrier's ids, then asks for the price and the date in parallel. A model should not have to chain four calls and carry UUIDs between them.

  • Plain numbers out. Monobank answers in kopiykas and numeric currency codes; the tools return 12500.5 and "UAH". A foreign payment keeps its original amount next to the hryvnia one.

  • Limits become advice. Monobank allows one personal request a minute and 31 days per statement. The server refuses a longer period before calling the bank and turns a 429 into "wait a minute and ask again" instead of a stack trace. Exchange rates are cached for five minutes, which is how often the bank refreshes them.

  • "Not found" is an answer. An unknown tracking number comes back as found: false, not as an empty parcel or an error.

How it was checked

Part

Check

All seven tools

20 tests that call the tools through a real MCP client over an in-memory transport.

np_find_branch, np_quote, np_track, mono_rates

npm run smoke starts the built server over stdio and calls the live services. Passing on 2026-11-16.

np_track on a delivered parcel

Fixture only: the field set is a live answer, the values are invented. No real tracking number was used.

ukrposhta_track

Fixture only, written from the example in Ukrposhta's Status Tracking documentation. Not run against the live service: the bearer is issued under an agreement.

mono_accounts, mono_statement

Fixture only, written from the field list in Monobank's API documentation. Not run against a live account.

The Nova Poshta fixtures and the exchange rates in fixtures/ are trimmed answers of the live services, so the tests parse what the services really send. The live smoke found one bug the fixtures could not: parcel lockers were filtered out of the first page of branches, which in a large city holds none. The carrier now does that filtering.

Tool-selection eval

npm run eval asks 23 questions in Ukrainian, Russian and English through the Claude Code CLI with only this server's tools available, and compares the first tool the model calls, and its arguments, with the expected ones. Four of the questions have no fitting tool (weather, another carrier, a money transfer, creating a waybill) and pass only if no tool is called.

Last run, 2026-11-16, claude-haiku-5-5: 23 of 23. The full record is in evals/last-report.json.

Read that number with care. The questions and the tool descriptions were written by the same person, so this is a regression check on the descriptions, not a measure of how the server does with questions from the wild. During the eval the services are answered from fixtures: it costs them nothing and no token leaves the machine.

Other servers

Nova Poshta has a larger MCP server, shopanaio/carrier-api, which also creates and manages waybills; several community servers cover Monobank. This one is narrower on purpose: three services behind one small tool list, no writes, and a published check of whether a model picks the right tool.

Layout

src/
  server.ts       tool list, descriptions and input schemas
  novaposhta.ts   tracking, branch search, quote
  ukrposhta.ts    tracking
  monobank.ts     rates, accounts, statement
  http.ts         one fetch wrapper with a timeout and a service-named error
fixtures/         saved answers of the services
scripts/smoke.ts  live check over stdio
evals/            cases, the offline server and the runner

MIT.

Available Tools

4 tools
mono_ratesMonobank: exchange ratesA
Read-only

Monobank exchange rates against the hryvnia: the price the bank buys and sells a currency at, or a cross rate for the less common ones. USD, EUR, PLN and GBP by default.

Inputs: currencies.

np_find_branchNova Poshta: find a branch or parcel lockerA
Read-only

Nova Poshta branches (відділення) and parcel lockers (поштомати) in a city or village: address, opening hours, weight limit and whether it is working now. Narrow it with a branch number or part of a street name.

Inputs: city (required), kind, limit, query.

np_quoteNova Poshta: delivery cost and dateA
Read-only

What a Nova Poshta parcel between two places costs and when it would arrive if sent now. Takes city names, not codes. Use it for "how much to send" and "how long does delivery take" questions about Nova Poshta.

Inputs: to (required), from (required), weight_kg (required), service, +1 more.

np_trackNova Poshta: where is the parcelA
Read-only

Current status of Nova Poshta parcels by tracking number (ТТН, 14 digits, usually starting with 2 or 5): where the parcel is, when it is expected, whether it was picked up. Up to 20 numbers at once. Give the sender or recipient phone to also get weight, cost and contents.

Inputs: numbers (required), phone.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: parcel tracking, branch lookup, delivery cost/time quoting, and currency exchange rates. The only potential overlap between np_track and np_quote is resolved by their descriptions: status of an existing parcel versus cost/time for a hypothetical new shipment.

    Naming Consistency4/5

    All names use snake_case and follow a service-prefix convention (np_ for Nova Poshta, mono_ for Monobank). The verb style is mostly consistent within np_ tools, though mono_rates is a noun phrase rather than a verb_noun pattern, which is a minor deviation.

    Tool Count5/5

    Four tools is well within the appropriate 3–15 range for a focused utility server, and each tool covers a distinct operation. There are no redundant or filler tools.

    Completeness4/5

    The Nova Poshta surface covers tracking, branch lookup, and delivery quoting, while Monobank has exchange rates. Minor gaps exist, such as no city lookup to support np_quote or broader Monobank operations, but the core utility workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only access to company data across PostgreSQL, MongoDB Atlas, and flat files through MCP tools, allowing AI assistants to query and retrieve information via natural language.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query live MoySklad data — inventory, sales, cash flow, documents, and analytics — through read-only MCP tools that match the dashboard's metrics.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents and chat clients to inspect proxy tokens, usage, pools, geo targeting, and build ready-to-use proxy connection URLs via the Litport account API, while remaining read-only.
      358 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an AI assistant to query Ukrainian software cash register data—receipts, shifts, X/Z reports, goods, and orders—and, only with explicit write permission, to open or close shifts and create fiscal receipts.
      16
      MIT