PostNL快递服务MCP服务器

postnl-mcp

一个 模型上下文协议 （MCP）服务器 PostNL API创建货件、生成条形码、跟踪包裹、计算交货日期和查找取货点——所有这些都是通过人工智能应用程序中的自然语言。

让我们来： 这是一个非官方的，由社区维护的项目，不与PostNL相关或批准。

社区建设 模型上下文协议 （MCP）服务器 PostNL API.创建货物、生成条形码、跟踪包裹、计算交货日期和查找取货地点——所有这些都可以通过任何兼容MCP的AI客户端使用自然语言完成。

注： 这是一个非官方的、由社区维护的项目，与PostNL无关或不受其认可。

快速启动

你不需要克隆这个仓库。

1. 确保安装了 Node.js 20+（您的 AI 应用程序正在运行） npx op-je机器）
2. 获取PostNL API数据（见 API密钥设置)
3. 将服务器添加为 AI 应用程序中的 MCP 服务器（复制下面的配置）
4. 用简单的荷兰语提问（见 例子)

快速入门（非开发人员）

您不需要克隆此仓库。

1. 确保已安装Node.js 20+（您的AI应用程序将运行 npx 在您的机器上）
2. 获取PostNL凭据（请参阅 API密钥设置)
3. 将此添加为AI应用程序中的MCP服务器（复制/粘贴下面的配置）
4. 提出简单的运输/跟踪问题（请参阅 示例用法)

添加到Claude桌面（也适用于协作）

Cowork在Claude Desktop内部运行，并使用相同的连接MCP服务器和权限。

1. 打开您的Claude Desktop MCP配置文件：
   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • 窗户： %APPDATA%\\Claude\\claude_desktop_config.json
2. 添加此服务器条目（或合并到现有条目中 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. 重新启动克劳德桌面

添加到其他AI应用程序

大多数MCP应用程序都有一个“添加MCP服务器”屏幕，您可以在其中填写：

• 命令： npx
• Args： -y postnl-mcp
• 环境： POSTNL_API_KEY=..., POSTNL_CUSTOMER_CODE=..., POSTNL_CUSTOMER_NUMBER=...

如果您的应用程序需要JSON，请粘贴此内容并将顶级密钥名称调整到您的客户端（常见密钥为 mcpServers, servers，或 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"
      }
    }
  }
}

故障排除

• 错误： Missing required env vars 或启动验证错误。
  • 修复：添加 POSTNL_API_KEY, POSTNL_CUSTOMER_CODE，以及 POSTNL_CUSTOMER_NUMBER 到服务器 env 并重新启动您的应用程序。
• 错误： npx: command not found 或者服务器无法启动。
  • 修复：安装Node.js 20+并重新启动应用程序。
• 已连接但API调用失败 401/403 或空的业务数据。
  • 修复：验证您使用的工具的PostNL API订阅（请参阅 必需的API订阅).

特性

• 7工具 涵盖PostNL航运API的4个类别
• 条形码生成 适用于国内（3S）、邮箱（2S）、欧盟（CC/CP/CD/CF）和国际（LA/RI/UE）运输
• 发货创建 带有运输标签生成功能（PDF或ZPL格式）
• 包裹追踪 具有完整的状态历史和事件时间线
• 交货日期计算 支持原产国和邮政编码
• 交货时间表 提供晚间配送和周日分拣选项
• 定位仪 --按邮政编码、城市或坐标搜索PostNL上下车点
• 输入验证 通过每个工具上的Zod模式实现安全、可预测的操作
• 响应缓存 具有可配置的TTL和写入时自动失效功能
• 费率限制处理 具有指数回退和 Retry-After 标头支持
• 工具集过滤 仅公开所需的工具类别
• Docker支持 通过GHCR进行集装箱化部署
• 可操作的错误消息 具有上下文感知的恢复建议

支持的客户

{
  "<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

配置

必需的

从获取您的API证书 PostNL开发者门户您的客户代码和客户编号可以在您的PostNL商业账户中找到。

可选的

API密钥设置

创建API密钥

1. 注册a PostNL开发者门户 账户
2. 订阅您需要的API（发货、条形码、交货日期等）
3. 为应用程序生成API密钥
4. 找到你的 客户代码 和 客户编号 在您的PostNL商业合同或门户中

必需的API订阅

根据您使用的工具，订阅：

可用工具

运输

追踪

交付

位置

工具集筛选

通过仅启用所需的工具类别来减少上下文窗口的使用。设置 POSTNL_TOOLSETS 将环境变量转换为逗号分隔的列表：

POSTNL_TOOLSETS=shipping,tracking

如果未设置，则启用所有工具集。无效名称将被忽略；如果所有名称都无效，则启用所有工具集作为回退。

条形码类型

PostNL根据货物使用不同的条形码类型：

常见产品代码

晚间配送不是单独的产品代码——使用任何兼容的产品代码（例如。 3085)带产品选项 {Characteristic: "118", Option: "006"} 和一个 DeliveryDate.

例子

一旦连接，您可以用简单的荷兰语提问：

• “为国内包裹生成条形码”
• “从我位于阿姆斯特丹Hoofdstraat 1的仓库发货到鹿特丹Kerkstraat 42”
• “按照包3STBJG123456789”
• “如果我今天发货，邮政编码1234AB的预期交货日期是多少？”
• “显示2511 BT Den Haag的交货时间”
• “查找邮政编码3011 AA的PostNL取款点”
• “提供PostNL位置176227的详细信息”

示例用法

连接后，您可以使用自然语言与PostNL API进行交互：

• “为国内包裹生成条形码”
• “创建从我位于阿姆斯特丹Hoofdstraat 1的仓库到鹿特丹Kerkstraat 42的货物”
• “轨道包裹3STBJG123456789”
• “如果我今天发货，邮政编码1234AB的预计交货日期是什么时候？”
• “显示2511 BT Den Haag的交货时间表”
• “查找邮政编码3011 AA附近的PostNL取件点”
• “获取PostNL位置176227的详细信息”

社区

• 技术支持： 支持.md
• 安全报告： 安全.md
• 贡献指南： 贡献.md
• Bug报告和功能请求： 问题

发展

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

项目结构

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

需求

• Node.js>=20
• A. 邮政公司 具有API凭证的业务帐户

许可证

麻省理工学院-见 许可证 了解详情。