novaposhta — Claude Code MCP server: setup and use
Connects Nova Poshta services to AI assistants for shipment tracking, address lookup, delivery estimates, and waybill work.
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-serverWhat novaposhta 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.
What it helps with
- 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 for the agent
- 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.
How to install novaposhta
Platform CLI
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-serverReplace <…> with your own values
Platform CLI
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-serverReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about novaposhta
How do I install novaposhta in Claude Code?
Run claude mcp add novaposhta -e NOVA_POSHTA_API_KEY=<NOVA_POSHTA_API_KEY> -- npx -y @shopana/novaposhta-mcp-server. Then restart or reload the MCP client.
What does novaposhta do?
It gives an AI assistant Nova Poshta tools for shipment tracking, location searches, delivery-cost estimates, reference lookups, and waybill operations.
Which novaposhta features need an API key?
The key is required for waybill actions, address changes, counterparty operations, and contact-person management. Tracking, address searches, and reference tools work without authentication.
