postnord-mcp

An MCP (Model Context Protocol) server for PostNord's REST APIs. Lets AI assistants like Claude track shipments, find pickup points, and estimate transit times across the Nordics (Sweden, Norway, Denmark, Finland).

You: Where is my package 84971563697SE?
Claude: → track_shipment("84971563697SE")
        Your package left the Oslo terminal this morning and is expected
        at your pickup point tomorrow between 08:00 and 16:00.

Tools

Prerequisites

• Node.js 18+

• A PostNord API key — free. All PostNord API plans are free of charge; the key is emailed to you after you register for a plan. Which registration to use depends on whether you have a company/organization number (see below).

Getting an API key

PostNord's developer portal is business-oriented. There is no consumer plan — every option authenticates with an API key sent as the apikey query parameter, but the registration paths differ:

• Sandbox is the quickest way to verify the server works end to end. The signup form only asks for a name, email, username, and password; set POSTNORD_SANDBOX=true (see Configuration) to point the server at the test host.

• Customer Plan vs Partner Plan — both are free. "Customer" is for using the APIs for your own business; "Partner" is for building a platform that serves other PostNord customers. Both require a company name and organization number at signup. If you run a sole proprietorship you already have an org number and can use the Customer Plan.

• No company? For real (non-sandbox) tracking without an organization number, email api.support@postnord.com and ask whether the free Customer Plan can be granted to an individual/hobby project.

The Booking API requires a separate business agreement and OAuth2 client credentials, and is not included in this server.

Installation

git clone https://github.com/fredrsat/postnord-mcp.git
cd postnord-mcp
npm install
npm run build

Usage

Claude Desktop

Add to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "postnord": {
      "command": "node",
      "args": ["/path/to/postnord-mcp/dist/index.js"],
      "env": {
        "POSTNORD_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add postnord --env POSTNORD_API_KEY=your-api-key -- node /path/to/postnord-mcp/dist/index.js

Any other MCP client

The server speaks MCP over stdio. Start it with POSTNORD_API_KEY set:

POSTNORD_API_KEY=your-api-key node dist/index.js

Configuration

All configuration is via environment variables:

Example prompts

Once connected, try asking your assistant:

• "Track package 84971563697SE"

• "Where's the nearest PostNord pickup point to Karl Johans gate 1, Oslo?"

• "Find service points near postal code 111 20 in Sweden"

• "How long does MyPack Collect take from 0150 Oslo to 5003 Bergen?"

API notes

• PostNord authenticates with the API key as an apikey query parameter on every request.

• Tracking uses Track & Trace v5 (/rest/shipment/v5/trackandtrace/findByIdentifier.json); service points use Business Location v5.

• The transit time endpoint varies by plan and agreement — if get_transit_time returns a 404, check the exact path in the swagger spec under your account on the developer portal and adjust src/postnord.ts.

• Rate limits depend on your plan (Sandbox / Free / Premium). API errors are returned to the model as tool errors with the response body included, so the assistant can explain what went wrong.

Development

npm run dev      # tsc --watch
npm run build    # compile to dist/

The code is small on purpose: src/postnord.ts is a thin API client, src/index.ts registers the MCP tools. Adding a new PostNord endpoint is a method on the client plus a registerTool call.

You can test the server manually with the MCP Inspector:

POSTNORD_API_KEY=your-api-key npx @modelcontextprotocol/inspector node dist/index.js

Roadmap

• Booking API support (requires a PostNord business agreement + OAuth2 client credentials)

• Publish to npm for npx postnord-mcp usage

• Response trimming — return curated fields instead of raw API JSON to save tokens

Contributions welcome — open an issue or PR.

Disclaimer

This is an unofficial, community-built integration. It is not affiliated with or endorsed by PostNord AB. Use of the PostNord APIs is subject to their terms of service.

License

MIT