postnl-mcp

Een Model Context Protocol (MCP) server voor de PostNL API. Maak zendingen aan, genereer barcodes, volg pakketten, bereken bezorgdata en vind afhaalpunten — allemaal via natuurlijke taal in je AI-app.

Let op: Dit is een onofficieel, community-onderhouden project en is niet verbonden aan of goedgekeurd door PostNL.

A community-built Model Context Protocol (MCP) server for the PostNL API. Create shipments, generate barcodes, track parcels, calculate delivery dates, and find pickup locations — all through natural language via any MCP-compatible AI client.

Note: This is an unofficial, community-maintained project and is not affiliated with or endorsed by PostNL.

Snel starten

Je hoeft deze repo niet te clonen.

1. Zorg dat Node.js 20+ is geïnstalleerd (je AI-app draait npx op je machine)
2. Haal PostNL API-gegevens op (zie API Key Setup)
3. Voeg de server toe als MCP server in je AI-app (kopieer onderstaande configuratie)
4. Stel vragen in gewoon Nederlands (zie Voorbeelden)

Quick Start (Non-Developers)

You do not need to clone this repo.

1. Make sure Node.js 20+ is installed (your AI app will run npx on your machine)
2. Get PostNL credentials (see API Key Setup)
3. Add this as an MCP server in your AI app (copy/paste config below)
4. Ask plain-language shipping/tracking questions (see Example Usage)

Add To Claude Desktop (Also Works In Cowork)

Cowork runs inside Claude Desktop and uses the same connected MCP servers and permissions.

1. Open your Claude Desktop MCP config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\\Claude\\claude_desktop_config.json
2. Add this server entry (or merge into existing mcpServers):

{
  "mcpServers": {
    "postnl-mcp": {
      "command": "npx",
      "args": ["-y", "postnl-mcp"],
      "env": {
        "POSTNL_API_KEY": "your-api-key",
        "POSTNL_CUSTOMER_CODE": "your-customer-code",
        "POSTNL_CUSTOMER_NUMBER": "your-customer-number"
      }
    }
  }
}

3. Restart Claude Desktop

Add To Other AI Apps

Most MCP apps have an "Add MCP Server" screen where you can fill in:

• Command: npx
• Args: -y postnl-mcp
• Env: POSTNL_API_KEY=..., POSTNL_CUSTOMER_CODE=..., POSTNL_CUSTOMER_NUMBER=...

If your app wants JSON, paste this and adapt the top-level key name to your client (common keys are mcpServers, servers, or context_servers):

{
  "<servers-key>": {
    "postnl-mcp": {
      "command": "npx",
      "args": ["-y", "postnl-mcp"],
      "env": {
        "POSTNL_API_KEY": "your-api-key",
        "POSTNL_CUSTOMER_CODE": "your-customer-code",
        "POSTNL_CUSTOMER_NUMBER": "your-customer-number"
      }
    }
  }
}

Troubleshooting

• Error: Missing required env vars or startup validation errors.
  • Fix: add POSTNL_API_KEY, POSTNL_CUSTOMER_CODE, and POSTNL_CUSTOMER_NUMBER to server env and restart your app.
• Error: npx: command not found or server fails to start.
  • Fix: install Node.js 20+ and restart your app.
• Connected but API calls fail with 401/403 or empty business data.
  • Fix: verify PostNL API subscriptions for the tools you use (see Required API Subscriptions).

Features

• 7 tools across 4 categories covering the PostNL Shipping APIs
• Barcode generation for domestic (3S), mailbox (2S), EU (CC/CP/CD/CF), and international (LA/RI/UE) shipments
• Shipment creation with shipping label generation (PDF or ZPL format)
• Parcel tracking with full status history and event timeline
• Delivery date calculation with origin country and postal code support
• Delivery timeframes with evening delivery and Sunday sorting options
• Location finder — search PostNL pickup/drop-off points by postal code, city, or coordinates
• Input validation via Zod schemas on every tool for safe, predictable operations
• Response caching with configurable TTL and automatic invalidation on writes
• Rate limit handling with exponential backoff and Retry-After header support
• Toolset filtering to expose only the tool categories you need
• Docker support for containerized deployment via GHCR
• Actionable error messages with context-aware recovery suggestions

Supported Clients

{
  "<servers-key>": {
    "postnl-mcp": {
      "command": "npx",
      "args": ["-y", "postnl-mcp"],
      "env": {
        "POSTNL_API_KEY": "your-api-key",
        "POSTNL_CUSTOMER_CODE": "your-customer-code",
        "POSTNL_CUSTOMER_NUMBER": "your-customer-number"
      }
    }
  }
}

claude mcp add --scope user postnl-mcp \
  --env POSTNL_API_KEY=your-api-key \
  --env POSTNL_CUSTOMER_CODE=your-customer-code \
  --env POSTNL_CUSTOMER_NUMBER=your-customer-number \
  -- npx -y postnl-mcp

codex mcp add postnl-mcp \
  --env POSTNL_API_KEY=your-api-key \
  --env POSTNL_CUSTOMER_CODE=your-customer-code \
  --env POSTNL_CUSTOMER_NUMBER=your-customer-number \
  -- npx -y postnl-mcp

[mcp_servers.postnl-mcp]
command = "npx"
args = ["-y", "postnl-mcp"]
env = { "POSTNL_API_KEY" = "your-api-key", "POSTNL_CUSTOMER_CODE" = "your-customer-code", "POSTNL_CUSTOMER_NUMBER" = "your-customer-number" }

gemini mcp add postnl-mcp -- npx -y postnl-mcp

docker run -i --rm \
  -e POSTNL_API_KEY=your-api-key \
  -e POSTNL_CUSTOMER_CODE=your-customer-code \
  -e POSTNL_CUSTOMER_NUMBER=your-customer-number \
  ghcr.io/bartwaardenburg/postnl-mcp

Configuration

Required

Get your API credentials from the PostNL Developer Portal. Your customer code and customer number can be found in your PostNL business account.

Optional

API Key Setup

Creating Your API Key

1. Register for a PostNL Developer Portal account
2. Subscribe to the APIs you need (Shipment, Barcode, Delivery Date, etc.)
3. Generate an API key for your application
4. Find your Customer Code and Customer Number in your PostNL business contract or portal

Required API Subscriptions

Depending on which tools you use, subscribe to:

Available Tools

Shipping

Tracking

Delivery

Locations

Toolset Filtering

Reduce context window usage by enabling only the tool categories you need. Set the POSTNL_TOOLSETS environment variable to a comma-separated list:

POSTNL_TOOLSETS=shipping,tracking

When not set, all toolsets are enabled. Invalid names are ignored; if all names are invalid, all toolsets are enabled as a fallback.

Barcode Types

PostNL uses different barcode types depending on the shipment:

Common Product Codes

Evening delivery is not a separate product code — use any compatible product code (e.g. 3085) with product option {Characteristic: "118", Option: "006"} and a DeliveryDate.

Voorbeelden

Eenmaal verbonden kun je in gewoon Nederlands vragen stellen:

• "Genereer een barcode voor een binnenlands pakket"
• "Maak een zending aan van mijn magazijn op Hoofdstraat 1, Amsterdam naar Kerkstraat 42, Rotterdam"
• "Volg pakket 3STBJG123456789"
• "Wat is de verwachte bezorgdatum voor postcode 1234AB als ik vandaag verstuur?"
• "Toon bezorgtijdvakken voor 2511 BT Den Haag"
• "Zoek PostNL afhaalpunten bij postcode 3011 AA"
• "Geef details van PostNL locatie 176227"

Example Usage

Once connected, you can interact with the PostNL API using natural language:

• "Generate a barcode for a domestic parcel"
• "Create a shipment from my warehouse at Hoofdstraat 1, Amsterdam to Kerkstraat 42, Rotterdam"
• "Track parcel 3STBJG123456789"
• "What's the expected delivery date for postal code 1234AB if I ship today?"
• "Show me delivery timeframes for 2511 BT Den Haag"
• "Find PostNL pickup points near postal code 3011 AA"
• "Get details of PostNL location 176227"

Community

• Support: SUPPORT.md
• Security reporting: SECURITY.md
• Contributing guidelines: CONTRIBUTING.md
• Bug reports and feature requests: Issues

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

Project Structure

src/
  index.ts              # Entry point (stdio transport)
  server.ts             # MCP server setup and toolset filtering
  postnl-client.ts      # PostNL API HTTP client with caching and retry
  cache.ts              # TTL-based in-memory response cache
  types.ts              # TypeScript interfaces for PostNL API
  tool-result.ts        # Error formatting with recovery suggestions
  update-checker.ts     # NPM update notifications
  tools/
    shipping.ts         # Barcode generation and shipment creation
    tracking.ts         # Parcel tracking by barcode
    delivery.ts         # Delivery date and timeframe calculation
    locations.ts        # PostNL location finder

Requirements

• Node.js >= 20
• A PostNL business account with API credentials

License

MIT - see LICENSE for details.