DEV Community

Philipp Sapronov
Philipp Sapronov

Posted on

Let Your AI Build Nova Poshta Integrations in Minutes

#ai #mcp #api #agents

🚀🚀🚀 We’re very excited to introduce Nova Poshta MCP Server — a developer-first way to let your AI 🤖 talk to the real Nova Poshta API without living in the docs. Built for AI assistants and dev workflows with AI agents. ✨✨✨

MCP Demo in Cursor.ai IDE

Skip the Docs-Driven Nova Poshta Routine

When a project gets the task “integrate Nova Poshta delivery”, technically everything is already clear:

  • there’s the official Nova Poshta API,
  • there are request examples,
  • there are dozens of existing integrations.

But in practice, every time it comes down to the same things:

  • remembering which method is responsible for tracking;
  • not mixing up fields when creating an express waybill;
  • building the right filters for branches;
  • figuring out why a “successful” response still returns no data.

Even if you already use AI assistants (Cursor, Claude, OpenAI, etc.), they often hallucinate 🤯: invent non-existent fields, wrong methods, incorrect formats. Simply because they don’t know the real Nova Poshta API schema.

Nova Poshta MCP Server is built specifically to fix that.

What It Is

Nova Poshta MCP Server is a layer that:

  • teaches your AI assistant 🤖 the real Nova Poshta API;
  • gives it tools with strict schemas (tracking, warehouses, waybills, reference data);
  • lets the assistant make API calls (including test requests) and rely on real responses.

The main goal:

So that a developer opens the documentation as rarely as possible
and more often gets ready-to-run code and clear explanations. 🚀

The fact that you can use this server for real transactions (creating waybills, searching branches, etc.) is a bonus.
The core scenario is: “AI 🤖 as a smart Nova Poshta API assistant for developers”, not “a new admin panel”.

How It Feels in Real Work

1. Implementing a New Feature ✨

Task: add order tracking to a customer portal or admin panel.

Normally you would:

  • search for the right method in the docs,
  • unpack all the parameters,
  • assemble the request,
  • map the response into your own format.

With Nova Poshta MCP Server:

  • in your AI assistant 🤖 you describe the task:
    “Write a TypeScript function that takes a TTN and returns a compact shipment status object for the UI.”

  • the assistant uses MCP server tools:

    • it knows which method to call,
    • it knows which fields are required,
    • it sees the real response schema;

  • as a result, you get real code built on top of a type-safe client, not a random fetch with made-up fields.

2. Understanding and Refactoring an Existing Integration

Task: your project already has a Nova Poshta integration, but:

  • it was written by someone else;
  • part of the logic is “magic” fields in the payload;
  • you need to change or extend it.

Normally you would:

  • dive into the documentation,
  • try to map the current code to API methods,
  • manually figure out what SeatsAmount does and how it differs from VolumeGeneral, etc.

With Nova Poshta MCP Server:

  • you give the AI assistant 🤖 a piece of code and ask: “Explain what this Nova Poshta request does and which fields are critical. Suggest a cleaner version using the client.”

  • relying on real method and type definitions, the assistant can:

    • decode the fields,
    • show which ones are required,
    • suggest a refactor on top of the official client.

3. Exploring and Running Test Requests 🔍

Task: quickly explore API capabilities for a specific scenario.

For example:

  • “What filters are available for searching branches?”
  • “Can I filter branches by POS terminal and type at the same time?”
  • “What does the full response for this waybill payload look like?”

With Nova Poshta MCP Server:

  • the AI agent 🤖 calls real Nova Poshta methods via MCP tools;
  • you see the actual JSON response, not an invented one;
  • you can quickly test hypotheses and adapt them to your code.

How This Differs from a Regular SDK

A regular SDK gives you:

  • functions/methods instead of manual fetch,
  • sometimes types and small wrappers.

Nova Poshta MCP Server + TS client give you:

  • a TypeScript client @shopana/novaposhta-api-client
    as a proper SDK for your application code;

  • plus an AI layer 🤖✨ that:

    • knows the same schemas and types,
    • can generate code on top of the client,
    • can explain what’s going on,
    • can run test requests.

In other words, your SDK and your AI agent⚡ share one and the same source of truth about the API instead of living separate lives. 🔗

What’s Inside (Very Briefly)

Under the hood:

  • @shopana/novaposhta-api-client
    Type-safe client: methods, request/response types, reference data.

  • Nova Poshta MCP Server

    • compatible with MCP clients (Claude, Cursor, etc.);
    • registers a set of tools for working with Nova Poshta;
    • internally uses that same TS client.

For a developer, this means:

  • in your code, you use the client as a normal library;
  • in your AI assistant, the same knowledge is exposed as convenient tools. 🤝

Getting Started With an AI Assistant 🚀

If you’re using Claude Desktop, Cursor, or any other MCP-compatible 🧩 client:

  1. Open your MCP config (for example, .claude/config.json or .mcp.json).
  2. Add the Nova Poshta MCP Server.
  3. Restart the assistant.

Example configuration:

{
  "mcpServers": {
    "novaposhta": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@shopana/novaposhta-mcp-server", "novaposhta-mcp"],
      "env": {
        "NOVA_POSHTA_API_KEY": "your_actual_api_key_here",
        "NOVA_POSHTA_SYSTEM": "DevCentre",
        "LOG_LEVEL": "info"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

After that you can, without opening the docs, ask your AI agent 🤖⚡ to:

  • “Create a TypeScript tracking function for Nova Poshta by TTN with proper error handling.”
  • “Prepare code that finds branches with a POS terminal in this city and returns them in a dropdown-friendly format.”
  • “Explain the fields returned when creating an express waybill and show the minimal working payload.”

The assistant will rely not on guesswork, but on the real Nova Poshta API — because behind it stands your MCP server and the TS client.

Where to look and how to give feedback

What’s next

If Nova Poshta is part of your product, you don’t have to fight the API alone anymore. Plug the Nova Poshta MCP Server into your AI assistant, install the TypeScript client in your app, and let the agent handle the boring parts: figuring out methods, fields, and payloads.

We’d love to see:

  • issues with scenario ideas,
  • bug reports from real integrations,
  • suggestions for new tools and schema improvements.

If this helps you ship faster, consider ⭐ starring the repo and sharing your use case — it really helps others discover an AI-friendly way to work with Nova Poshta. 🚀

Top comments (0)