Novaposhta

What the novaposhta MCP server does

The novaposhta MCP server gives MCP-compatible AI assistants access to selected Nova Poshta API capabilities. It is part of the @shopana/carrier-api monorepo and is implemented as a separate package named @shopana/novaposhta-mcp-server.

Its supported scope covers several common carrier workflows:

• Tracking Nova Poshta documents and parcels
• Searching for addresses and warehouses
• Looking up reference data
• Creating and managing waybills
• Working with carrier-related entities such as counterparties and contact people

The repository demonstrates queries for tracking a document, finding Kyiv warehouses with POS terminals, and calculating delivery cost for a parcel. These examples indicate that the server is intended for conversational shipping tasks rather than general-purpose data access.

How it works

The MCP package uses the Nova Poshta API client beneath the protocol layer. That client follows a plugin-based design with namespaced services for address, reference, tracking, waybill, counterparty, and contact-person operations. The MCP server exposes the relevant functionality as tools that an assistant can call.

Two transport modes are available: stdio for local desktop or command-line integrations, and HTTP for deployments that need an HTTP-based connection. The repository describes support for MCP 1.22 or later. Requests ultimately use Nova Poshta API authentication and require an API key.

Setup and configuration

Run the novaposhta MCP server with the package published as @shopana/novaposhta-mcp-server. The documented local command is:

npx @shopana/novaposhta-mcp-server

For an MCP client using a command-based configuration, invoke npx with the package and its novaposhta-mcp executable:

{
  "mcpServers": {
    "novaposhta": {
      "command": "npx",
      "args": ["-y", "-p", "@shopana/novaposhta-mcp-server", "novaposhta-mcp"],
      "env": {
        "NOVA_POSHTA_API_KEY": "your_api_key_here"
      }
    }
  }
}

The repository requires Node.js 18 or 20+ for development. Building from source uses Yarn 3+ and the workspace commands documented in the project.

Tools and capabilities

The novaposhta MCP server is suitable for assistant-driven carrier operations including:

• Shipment and document tracking
• City, address, and warehouse searches
• Reference lookups for shipping data
• Waybill creation and management
• Delivery-cost calculations, where supported by the connected Nova Poshta API workflow

The underlying client is written in TypeScript with strict typing and uses a transport-independent architecture. Those implementation details matter primarily when extending the package or embedding its client outside MCP.

Limitations and notes

The server requires a valid Nova Poshta API key; the provided setup does not describe an unauthenticated mode. The repository identifies Claude and other AI assistants as intended consumers, but it does not provide client-specific setup instructions beyond the MCP configuration example.

The material does not list individual MCP tool names, complete input schemas, rate limits, or the exact HTTP startup command. Consult the package documentation and Nova Poshta’s official API documentation before relying on a particular operation in production.