novaposhta

---

概述

@shopana/novaposhta-mcp-server 是一个可用于生产环境的 Nova Poshta MCP 服务，可让你直接通过 Cursor、Claude Code、OpenAI、Gemini 等 AI 助手以及任何兼容 MCP 的客户端处理乌克兰的运输和物流数据。 它基于类型安全的 @shopana/novaposhta-api-client 构建，将 Nova Poshta 的追踪、地址和网点搜索、运单管理及参考数据转化为简洁、适用于 AI 的工具，让你能够自动处理日常配送任务、加快开发工作流，并轻松将 Nova Poshta 集成到应用中。

功能

• 全面追踪：追踪单个或多个货件、查看物流记录并列出单据
• 地址查询：通过高级筛选搜索城市、居民点、街道和仓库
• 运单操作：以编程方式计算费用，以及创建、更新和删除运单
• 参考数据：访问货物类型、服务类型、付款方式等数据
• 类型安全：使用 TypeScript 构建，确保完整的类型安全
• 可用于生产环境：具备企业级错误处理和日志记录
• 零配置：采用合理的默认设置，开箱即用

快速开始

1. 获取 API 密钥（大多数操作可选）

**注意：**仅运单操作（创建、更新、删除）需要 API 密钥。追踪、地址搜索和参考数据均无需身份验证。

1. 在 Nova Poshta 注册
2. 前往“设置”→“API 密钥”
3. 生成新的 API 密钥

2. 配置服务

创建或更新 .mcp.json：

{
  "mcpServers": {
    "novaposhta": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@shopana/novaposhta-mcp-server", "novaposhta-mcp"],
      "env": {
        "NOVA_POSHTA_API_KEY": "your_actual_api_key_here",
        "NOVA_POSHTA_SYSTEM": "DevCentre",
        "LOG_LEVEL": "info"
      }
    }
  }
}

3. 重启 MCP 客户端

更新 MCP 配置后，需要重启或重新加载客户端

4. 开始使用

向 Claude 提问：

• “追踪 Nova Poshta 包裹 20450123456789”
• “查找基辅的仓库”
• “计算从基辅到利沃夫寄送 5kg 包裹的运费”
• “搜索哈尔科夫的街道”

配置

环境变量

变量	必需	默认值	描述
NOVA_POSHTA_API_KEY	部分必需*	-	你的 Nova Poshta API 密钥（*仅运单操作需要）
NOVA_POSHTA_SYSTEM	否	-	系统标识符参数。DevCentre 是 Nova Poshta API Sandbox UI 使用的值（可选，不影响功能）
LOG_LEVEL	否	info	日志级别：debug、info、warn、error

无需 API 密钥即可使用的操作：

• 追踪（track_document、track_multiple_documents、track_multiple、get_document_movement、get_document_list）
• 地址搜索（address_get_settlements、address_get_settlement_country_region、address_search_cities、address_search_settlements、address_search_streets、address_get_warehouses）
• 参考数据（所有 reference_* 工具）

需要 API 密钥的操作：

• 运单管理（waybill_calculate_cost、waybill_get_estimate、waybill_create、waybill_create_with_options、waybill_create_to_postomat、waybill_create_batch、waybill_update、waybill_delete、waybill_delete_batch、waybill_get_delivery_date）
• 地址管理（address_save、address_update、address_delete）
• 交易对手操作（counterparty_get_counterparties、counterparty_get_addresses、counterparty_get_contact_persons、counterparty_save、counterparty_update、counterparty_delete、counterparty_get_options）
• 联系人管理（contact_person_save、contact_person_update、contact_person_delete）

传输模式

stdio

适用于 Claude Desktop 和 Claude Code 等本地 AI 助手：

novaposhta-mcp
# or
node dist/cli.js

可用工具

追踪工具

track_document

根据单个 Nova Poshta 单据编号和可选的电话号码进行追踪，以获取实时状态、位置和预计送达时间。

track_multiple_documents

一次追踪多份 Nova Poshta 单据，并获取汇总统计信息。

track_multiple

追踪多份 Nova Poshta 单据，并获取整理后的结果和统计信息。返回成功或失败的追踪尝试，以及配送统计信息（已送达、运输中、仓库中的数量）。用于批量操作时，比 track_multiple_documents 更方便。

get_document_movement

获取最多 10 份单据的流转历史记录，包括状态和时间戳。

get_document_list

列出指定日期范围内创建的单据，支持分页。

---

地址工具

address_get_settlements

获取乌克兰的定居点地区（областей）。返回行政区域列表。将此公共目录缓存 12 小时。

address_get_settlement_country_region

获取指定地区的定居点国家地区（регіонів）。返回该行政区域内的地区列表。缓存 12 小时。

address_search_cities

按名称或邮政编码查找 Nova Poshta 城市。务必使用 limit 参数（建议值：10），以避免响应过大。

address_search_settlements

分页搜索定居点（城市、城镇、村庄）。务必使用 limit 参数（建议值：10），以避免响应过大。

address_search_streets

搜索定居点内的街道。用于上门取件／配送流程。务必使用 limit 参数（建议值：10），以避免响应过大。

address_get_warehouses

通过高级筛选列出 Nova Poshta 仓库（分部、自助取件柜、取件点）。务必使用 limit 参数（建议值：10-20），以避免响应过大。

address_save

为交易对方创建新地址。需要 API 密钥。响应会返回上门配送所需的 Ref 和 Description。

address_update

更新交易对方的现有地址。只能在使用该地址创建运单前编辑。

address_delete

根据引用删除交易对方地址。仅当该地址尚未用于电子单据时才允许删除。

---

运单工具

waybill_calculate_cost

计算货件的配送费用，并可选估算配送日期。可使用类型化字段或原始 API 负载。

waybill_get_estimate

通过一次调用获取完整的货件估算（价格 + 配送日期）。为方便起见，此工具会合并费用计算和配送日期估算。

waybill_create

创建标准 Nova Poshta 运单（电子单据）。这是基本的运单创建方法。

waybill_create_with_options

创建包含附加选项和服务的 Nova Poshta 运单。支持回寄、附加服务、第三方付款方和 RedBox 条形码。需要货到付款、保险或退货货件时，请使用此工具。

waybill_create_to_postomat

创建配送至收件人自提柜的运单。收件人自提柜限重 20 kg，且需要包含包裹尺寸的 OptionsSeat 数组。

外层请求使用 PascalCase 字段。OptionsSeat 内的字段使用 API 的 lower camel case 线格式。ServiceType 使用 DoorsPostomat 或 WarehousePostomat；CargoType 必须为 Parcel 或 Documents；申报的 Cost 不得超过 10,000 UAH；且 SeatsAmount 必须与 OptionsSeat 项目数相符。每个包裹限重 20 kg，宽度不得超过 40 cm，长度不得超过 60 cm，高度不得超过 30 cm。

{
  "request": {
    "PayerType": "Sender",
    "PaymentMethod": "Cash",
    "DateTime": "25.12.2024",
    "CargoType": "Parcel",
    "Weight": 1,
    "ServiceType": "WarehousePostomat",
    "SeatsAmount": 1,
    "Description": "Test package",
    "Cost": 500,
    "CitySender": "sender-city-ref",
    "Sender": "sender-counterparty-ref",
    "SenderAddress": "sender-branch-ref",
    "ContactSender": "sender-contact-ref",
    "SendersPhone": "380671234567",
    "CityRecipient": "recipient-city-ref",
    "Recipient": "recipient-counterparty-ref",
    "RecipientAddress": "recipient-postomat-ref",
    "RecipientWarehouseIndex": "11/1001",
    "ContactRecipient": "recipient-contact-ref",
    "RecipientsPhone": "380501234567",
    "OptionsSeat": [
      {
        "weight": 1,
        "volumetricWidth": 10,
        "volumetricLength": 20,
        "volumetricHeight": 15
      }
    ]
  }
}

waybill_create_for_postomat 仍可作为已弃用的兼容别名使用，并接受相同的请求。

使用 waybill_create 从自提柜寄件

从寄件人自提柜实际寄件时，请使用现有的 waybill_create 工具。将自提柜 Ref 作为 SenderAddress 传入。配送至网点时使用 WarehouseWarehouse，配送至地址时使用 WarehouseDoors。创建运单后，在 Nova Poshta 移动应用中选择该运单，即可打开柜门并装入包裹。

该工具使用与上文相同的自提柜限制，以及 lower camel case 格式的 OptionsSeat 字段。是否可用某种付款方式取决于寄件人账户。如果 Nova Poshta 拒绝付款方为 Sender 时使用 NonCash，请改用可用方式（例如 Cash），或检查交易对方选项。

查找网点时，Counterparty.City 不一定是可用的城市 Ref。必要时，请使用 CityDescription 搜索网点，并在运单中使用所选网点的 CityRef。MCP 服务会自动以递增间隔重试 API 限流错误代码 20000401501。

waybill_create_batch

按顺序批量创建多个运单。逐个处理每份运单，以避免触发限流。返回包含各项结果（包括任何错误）的数组。

waybill_update

更新现有运单。传入原始负载（必须包含 DocumentRef）。

waybill_delete

根据 DocumentRef 删除一份或多份运单。运单只能在进入处理流程前删除。

waybill_delete_batch

在一次 API 调用中，根据 DocumentRef 批量删除多份运单。运单只能在进入处理流程前删除。

waybill_get_delivery_date

获取一对城市及服务类型对应的预计配送日期。

---

参考工具

reference_get_cargo_types

列出 Nova Poshta 支持的货物类型。每月缓存此目录。取值：Parcel、Cargo、Documents、TiresWheels、Pallet。

reference_get_pack_list

列出可用包装类型及其标准尺寸和说明。可用于计算配送费用。每月缓存。

reference_get_tires_wheels_list

列出可用的轮胎和车轮类型。返回作为货物运输的轮胎和车轮类型及说明。每月缓存。

reference_get_cargo_description_list

列出货物描述，并支持可选搜索。返回常见货物类型的预定义描述。每月缓存。

reference_get_pickup_time_intervals

获取可用的取件时间段。返回 Nova Poshta 可从发件人处取件的时间范围。每小时缓存。

reference_get_backward_cargo_types

列出反向配送货物类型。返回可寄回的货物类型（文件、金钱等）。用于退货运输和货到付款。每月缓存。

reference_get_redelivery_payers

列出反向配送的付款方类型。返回可支付反向配送费用的一方（发件人／收件人）。用于退货运输。每月缓存。

reference_get_service_types

列出配送服务类型：WarehouseWarehouse、WarehouseDoors、DoorsWarehouse、DoorsDoors、DoorsPostomat 和 WarehousePostomat。每月缓存。

reference_get_payment_methods

列出货件支持的付款方式。返回 Cash／NonCash。非现金付款仅适用于与 Nova Poshta 签订合同的客户。

reference_get_pallet_types

列出托盘类型及其尺寸和重量规格。每月缓存，尤其是在提供托盘反向配送服务时。

reference_get_time_intervals

获取收件人所在城市可用的配送时间段。返回 Number/Start/End 条目。每月缓存。

reference_get_ownership_forms

列出创建交易对手所需的企业所有权形式。返回 ТОВ、ПрАТ、ФГ 等简称及全称。每月缓存。

reference_decode_message

将 Nova Poshta API 消息代码解码为易读文本。将数字代码映射为乌克兰语／俄语说明。

reference_get_types_of_payers

获取创建运单时的付款方类型列表。返回 Sender／Recipient／ThirdPerson。ThirdPerson 付款方仅在签订服务合约后可用。每月缓存。

reference_get_payment_forms

获取创建运单时的付款形式列表。返回 Cash／NonCash。非现金付款仅适用于签约客户。每月缓存。

reference_get_types_of_counterparties

获取交易对手类型列表。返回 PrivatePerson／Organization。每月刷新，以确保与发件人／收件人注册规则保持一致。

---

交易对手工具

counterparty_get_counterparties

按属性（Sender/Recipient/ThirdPerson）筛选并获取交易对手列表。需要 API 密钥。每日缓存。每页最多返回 500 行。

counterparty_get_addresses

获取特定交易对手的地址。需要 API 密钥。每日缓存。每页最多 500 条记录。

counterparty_get_contact_persons

获取交易对手的联系人。必须提供 API 密钥。每日缓存。使用分页，确保响应不超过 500 条记录。

counterparty_save

创建新的交易对手（个人或组织）。个人必须提供名字和姓氏。组织还必须发送 OwnershipForm 和 EDRPOU。需要 API 密钥。

counterparty_update

更新现有交易对手的详细信息。只能在使用该交易对手创建运单之前进行编辑。

counterparty_delete

按引用删除交易对手。**重要：**只能通过 API 删除收件人交易对手；清理发件人信息必须联系您的客户经理。

counterparty_get_options

获取交易对手选项和权限。返回 CanPayTheThirdPerson、CanSameDayDelivery、HideDeliveryCost 等布尔值。

---

联系人工具

contact_person_save

为交易对手创建新的联系人。需要 API 密钥。所有字段都必须使用乌克兰语填写。

contact_person_update

更新现有联系人详细信息。只有法人实体可以编辑完整资料。个人只能修改电话号码。仅当尚未为该交易对方签发运单时，才允许编辑。

contact_person_delete

按引用删除联系人。仅法人实体可通过 API 删除，且仅限该联系人尚未用于电子单据的情况。

使用示例

跟踪货件

给 Claude 的提示词：

Track Nova Poshta package 20450123456789

Claude 将使用 track_document 工具，并返回详细状态，包括当前位置、预计送达时间和收件人信息。

---

查找仓库

给 Claude 的提示词：

Find all Nova Poshta branches in Lviv that have POS terminals

Claude 将搜索利沃夫市，然后使用相应筛选条件列出带有 POS 终端的仓库。

---

计算配送费用

给 Claude 的提示词：

Calculate shipping cost for 10kg parcel from Kyiv to Odesa, warehouse to warehouse, declared value 2000 UAH

Claude 将查找城市引用，并计算配送费用和预计送达日期。

---

多单据跟踪

给 Claude 的提示词：

Track these packages: 20450123456789, 20450987654321, 20451234567890 and give me a summary

Claude 将使用批量跟踪工具，并提供汇总统计信息：已送达、运输中、待取件等。

项目结构

packages/novaposhta-mcp-server/
├── src/
│   ├── cli/           # CLI entry points
│   ├── tools/         # MCP tool implementations
│   │   ├── address.ts
│   │   ├── tracking.ts
│   │   ├── waybill.ts
│   │   └── reference.ts
│   ├── types/         # TypeScript type definitions
│   ├── utils/         # Utilities (logging, validation, etc.)
│   ├── config.ts      # Configuration management
│   └── server.ts      # MCP server implementation
├── dist/              # Compiled output
├── examples/          # Usage examples
├── tests/             # Test suites
└── package.json

调试

启用调试日志：

{
  "env": {
    "LOG_LEVEL": "debug"
  }
}

查看日志：

• stdio 模式：日志会写入 stderr

常见问题

一般问题

问：为什么要使用此 MCP 服务，而不是直接调用 Nova Poshta API？ 答：此 MCP 服务有以下几个主要优势：

• 全面的文档：所有工具都有完善的文档和清晰的说明，方便 AI 助手理解并正确使用
• 真实数据操作：使用实际 Nova Poshta 数据执行真实 API 调用，包括跟踪货件、计算费用、创建运单等
• 原生 AI 集成：专为 Claude 等 AI 助手设计，可通过自然语言与 Nova 交互

问：使用此服务需要 Nova Poshta 账户吗？ 答：需要，你必须在 my.novaposhta.ua 注册并生成 API 密钥。

问：这是 Nova Poshta 官方软件包吗？ 答：不是，这是由社区维护的软件包。官方 API 文档请访问 developers.novaposhta.ua。

问：可以在生产环境中使用吗？ 答：可以！此软件包已准备好用于生产环境，并具备企业级错误处理能力。

问：此软件包支持 Nova Poshta API 的所有功能吗？ 答：此软件包涵盖了最常用的功能。如果你需要其他功能，请提交问题。

---

更新日志

详细变更历史请参阅 CHANGELOG.md。

---

许可证

Apache License 2.0，详情请参阅 LICENSE。

链接

• MCP Registry - 在官方注册表中查找此服务
• Nova Poshta API 文档
• Model Context Protocol
• MCP SDK

支持

• 问题：GitHub Issues
• 讨论：GitHub Discussions
• 电子邮件：[email protected]

---