carrier-api

This MCP server provides an integration layer to expose Nova Poshta API functionality to AI assistants via the Model Context Protocol (MCP). It supports MCP 1.22+ features and offers tracking, address search, waybill creation and management, and access to reference data through a plugin-based API client. The server can operate in both stdio and HTTP transports, enabling Claude-like assistants or other MCP clients to issue structured requests and receive typed responses. To use it, configure the MCP in your client (for example in Claude Desktop) to load the novaposhta MCP server, supplying your Nova Poshta API key as an environment variable. You can then ask the assistant to track a document, search for warehouses, or fetch reference data, and the MCP server will handle the calls to the Nova Poshta API and return typed results.

Prerequisites:

• Node.js 18+ (or 20+) installed on your workstation or deployment environment
• Yarn 3+ if you plan to work with the monorepo locally
• Access to the npm/published MCP server package or ability to run npx

Option A: Run via npx without local install

1. Ensure you have an API key for Nova Poshta and keep it ready.
2. Use the MCP config below in your .mcp.json or Claude Desktop config. Example:

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

3. Run your MCP-enabled client (Claude, etc.) and reference the novaposhta MCP server by name (novaposhta).

Option B: Install locally and run (developer workflow)

1. Clone the repository or install the MCP server package directly:
   • npm i -D @shopana/novaposhta-mcp-server
2. Start the MCP server (adjust command as needed for your setup, e.g. node path/to/server.js if using a custom start script).
3. Configure your MCP client to point to the running server and provide the NOVA_POSHTA_API_KEY in environment variables.

Prerequisites recap:

• Node.js 18+ or 20+
• Access to Nova Poshta API key
• MCP client capable of loading MCP servers from config (e.g., Claude Desktop with .mcp.json)

Tips and common issues:

• Ensure NOVA_POSHTA_API_KEY is kept secure and not checked into version control.
• If you encounter transport issues, verify that the MCP server is reachable by your client (stdio vs HTTP transport). For HTTP, ensure CORS and network access are allowed where applicable.
• The MCP server supports both stdio and HTTP transports; you can switch modes via your MCP client configuration.
• The server exposes Nova Poshta services such as address search, tracking, waybill management, and reference data. Use precise query payloads to reduce error responses.
• When updating the MCP server package, revalidate your .mcp.json or Claude config to ensure the server name and path remain correct.
• If you customize the environment, you can add additional NOVA_POSHTA_API_KEY overrides per environment as needed by different deployment environments.