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

1. 添加此服务器条目（或合并到现有条目中 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"
      }
    }
  }
}

1. 重新启动克劳德桌面

添加到其他AI应用程序

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

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

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

故障排除

• 错误： 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进行集装箱化部署
• 可操作的错误消息 具有上下文感知的恢复建议

支持的客户

Advanced setup and supported clients (expand)

此MCP服务器未绑定到一个编码代理。它适用于任何可以启动stdio MCP服务器的MCP兼容客户端或代理运行时。

克劳德生态系统笔记

Claude目前有多个易于混淆的MCP相关概念：

• 本地MCP服务器（克劳德桌面）： 定义于 claude_desktop_config.json 然后在你的机器上开始(文档).
• 合作： 重用Claude Desktop中连接的MCP服务器(文档).
• 连接器： 在Claude中管理远程MCP集成(文档).
• 协作插件： Claude特定的工作流打包（说明+工具/数据集成）(文档).在Claude中很有用，但不能作为其他代理客户端的通用MCP服务器配置进行移植。

根据供应商文件验证 2026-03-05.

设置（高级用户）

如果快速入门在您的客户中有效，您可以跳过此部分。这些是额外的每个客户端设置选项和CLI单行程序。

通用MCP服务器配置

在任何主机中使用此作为基线：

• 命令： npx
• Args： ["-y", "postnl-mcp"]
• 必需的环境变量： POSTNL_API_KEY, POSTNL_CUSTOMER_CODE, POSTNL_CUSTOMER_NUMBER
• 可选环境变量： POSTNL_CACHE_TTL, POSTNL_MAX_RETRIES, POSTNL_TOOLSETS （参见 配置)

最小JSON（使顶级密钥适应您的主机）：

{
  "": {
    "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 CLI（OpenAI）

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

~/.codex/config.toml 备选方案：

[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 CLI（谷歌）

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

集 POSTNL_API_KEY, POSTNL_CUSTOMER_CODE，以及 POSTNL_CUSTOMER_NUMBER 在 ~/.gemini/settings.json.

VS代码（副本）

打开命令选项板(Cmd+Shift+P / Ctrl+Shift+P) > MCP: Add Server > 命令（stdio），或使用 .vscode/mcp.json 使用顶级密钥 servers 以及来自的规范命令/args/env块 通用MCP服务器配置.

克劳德桌面+协作/光标/风帆/克莱恩/泽德

Cowork在Claude Desktop内部运行，并使用相同的连接MCP服务器和权限。在Claude Desktop中配置一次，服务器就可以在Cowork中使用。

使用规范配置块，并将其与匹配的顶级密钥一起放置在下面的主机文件中。

码头工人

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

其他MCP客户端

使用以下值 通用MCP服务器配置.

术语

什么是可跨主机移植的：

• MCP服务器运行时设置(command, args, env)
• 运输模型(stdio 命令服务器）
• 此服务器公开的工具名称和工具模式

什么是特定于主机/供应商的（不可移植）：

• 主机配置密钥名称(servers, mcpServers, context_servers, mcp_servers)
• 主机UX/添加服务器的工作流（CLI命令、UI菜单、设置路径）
• 人类特有的概念，如 Claude Desktop本地MCP服务器, Claude连接器通过远程MCP，以及 Claude代码插件 用于联合工作流程

安全说明

• 信任模型： 允许调用此MCP服务器的任何提示或代理都可以使用配置的凭据执行PostNL API操作。
• 最低权限凭据： 每个环境/团队/用例使用单独的PostNL凭据，并且仅使用必需的API订阅。
• 书面行动批准： 为变异工具（装运创建和其他写入操作）启用主机端批准。
• 团队配置治理： 将共享MCP配置保留在版本控制中，要求检查命令/args/env/toolset过滤的更改，并将机密保存在vault或主机机密管理器中（而不是纯文本仓库文件中）。

配置

必需的

从获取您的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凭证的业务帐户

许可证

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