# novaposhta

Connects Nova Poshta services to AI assistants for shipment tracking, address lookup, delivery estimates, and waybill work.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 7
- Author: shopanaio
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/shopanaio/carrier-api/tree/HEAD/packages/novaposhta-mcp-server
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/novaposhta

## What it does

This MCP server exposes Nova Poshta capabilities to an AI assistant. It can follow one or many shipments, show movement details, list documents, search cities, streets, and warehouses, and provide reference data. Waybill tools cover delivery-cost estimates plus creation, updates, and deletion.

The server runs locally over `stdio` through `npx`. Configure it with `NOVA_POSHTA_API_KEY`, `NOVA_POSHTA_SYSTEM`, and `LOG_LEVEL`, then reload the MCP client. The API key is needed for waybill actions, address management, counterparties, and contact persons. Tracking, address lookup, and reference tools can run without it.

Waybill creation, editing, or removal will fail when `NOVA_POSHTA_API_KEY` is missing. This is the main setup constraint; basic tracking and directory searches do not depend on that key.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `NOVA_POSHTA_API_KEY`, `NOVA_POSHTA_SYSTEM`, `LOG_LEVEL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env NOVA_POSHTA_API_KEY=<NOVA_POSHTA_API_KEY> --env NOVA_POSHTA_SYSTEM=<NOVA_POSHTA_SYSTEM> --env LOG_LEVEL=<LOG_LEVEL> --transport stdio novaposhta-mcp-server -- npx -y @shopana/novaposhta-mcp-server
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add novaposhta-mcp-server --env NOVA_POSHTA_API_KEY=<NOVA_POSHTA_API_KEY> --env NOVA_POSHTA_SYSTEM=<NOVA_POSHTA_SYSTEM> --env LOG_LEVEL=<LOG_LEVEL> -- npx -y @shopana/novaposhta-mcp-server
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "novaposhta-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@shopana/novaposhta-mcp-server"
            ],
            "env": {
                "NOVA_POSHTA_API_KEY": "<NOVA_POSHTA_API_KEY>",
                "NOVA_POSHTA_SYSTEM": "<NOVA_POSHTA_SYSTEM>",
                "LOG_LEVEL": "<LOG_LEVEL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "novaposhta-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@shopana/novaposhta-mcp-server"
            ],
            "env": {
                "NOVA_POSHTA_API_KEY": "<NOVA_POSHTA_API_KEY>",
                "NOVA_POSHTA_SYSTEM": "<NOVA_POSHTA_SYSTEM>",
                "LOG_LEVEL": "<LOG_LEVEL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e NOVA_POSHTA_API_KEY=<NOVA_POSHTA_API_KEY> -e NOVA_POSHTA_SYSTEM=<NOVA_POSHTA_SYSTEM> -e LOG_LEVEL=<LOG_LEVEL> novaposhta-mcp-server npx -y @shopana/novaposhta-mcp-server
```
Replace <…> with your own values

## When to use it
- track one or several Nova Poshta shipments
- locate cities, streets, and warehouses
- estimate a delivery price
- create or update a waybill
- retrieve Nova Poshta reference data

## Example prompts
- Track Nova Poshta shipment 20450123456789 and show its current status.
- Find Nova Poshta warehouses in Kyiv.
- Calculate shipping from Kyiv to Lviv for a 5kg parcel.

## Similar
- [mcp-melhor-envio](https://affpapa.org/en/nevibecode/mcp/mcp-melhor-envio.md) — MCP server · ★ 274
- [c-tracking](https://affpapa.org/en/nevibecode/skills/c-tracking.md) — skill · ★ 173
- [mcp-skydropx](https://affpapa.org/en/nevibecode/mcp/mcp-skydropx.md) — MCP server · ★ 274
- [ae-data-integration-helper](https://affpapa.org/en/nevibecode/skills/ae-data-integration-helper.md) — skill · 791 installs
- [ae-generate-tracking-code](https://affpapa.org/en/nevibecode/skills/ae-generate-tracking-code.md) — skill · 789 installs
- [Vessel Traffic MCP](https://affpapa.org/en/nevibecode/mcp/vessel-traffic-mcp.md) — MCP server · ★ 8

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md