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. ［Settings → API Keys］に移動します
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 を追跡して」
• 「Kyiv の倉庫を探して」
• 「5kg の荷物を Kyiv から Lviv へ送る場合の送料を計算して」
• 「Kharkiv の通りを検索して」

設定

環境変数

変数	必須	デフォルト	説明
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

複数の送り状を順番に一括作成します。レート制限を回避するため、各送り状を 1 件ずつ処理します。エラーを含む結果の配列を返します。

waybill_update

既存の送り状を更新します。生ペイロードを渡してください（DocumentRef を含める必要があります）。

waybill_delete

DocumentRef を指定して、1 件または複数の送り状を削除します。送り状は処理に入る前に限り削除できます。

waybill_delete_batch

DocumentRef を指定して、1 回の API 呼び出しで複数の送り状を一括削除します。送り状は処理に入る前に限り削除できます。

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 が差出人から荷物を集荷できる時間帯を返します。1時間ごとにキャッシュします。

reference_get_backward_cargo_types

返送貨物の種類を一覧表示します。返送可能な貨物（書類、金銭など）の種類を返します。返送および代金引換に使用します。月次でキャッシュします。

reference_get_redelivery_payers

返送時の支払者の種類を一覧表示します。返送の支払者（Sender／Recipient）を返します。返送に使用します。月次でキャッシュします。

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 キーが必要です。日次でキャッシュします。1ページあたり最大500件です。

counterparty_get_addresses

特定の取引先の住所を取得します。API キーが必要です。日次でキャッシュします。1ページあたり最大500件です。

counterparty_get_contact_persons

取引先の連絡担当者を取得します。API キーは必須です。日次でキャッシュします。応答上限の500件を超えないよう、ページングを使用してください。

counterparty_save

新しい取引先（個人または法人）を作成します。個人の場合、名と姓が必要です。法人の場合は OwnershipForm と EDRPOU も送信する必要があります。API キーが必要です。

counterparty_update

既存の取引先情報を更新します。その取引先を使用した運送状を作成する前に限り、編集できます。

counterparty_delete

参照情報で取引先を削除します。重要： API で削除できるのは Recipient の取引先のみです。Sender の整理はアカウントマネージャーを通じて行う必要があります。

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 に書き込まれます

よくある質問

一般的な質問

Q: Nova Poshta API を直接呼び出す代わりに、この MCP サーバーを使うべき理由は何ですか？ A: この MCP サーバーには、次のような主な利点があります：

• 包括的なドキュメント：すべてのツールに明確な説明が付いた詳しいドキュメントがあり、AI アシスタントが内容を理解して正しく使用できます
• 実データを使った操作：実際の Nova Poshta データを使って API 呼び出しを実行できます。荷物の追跡、料金の計算、送り状の作成などが可能です
• AI に適した連携：Claude などの AI アシスタント向けに設計されており、Nova と自然言語でやり取りできます

Q: これを使うには Nova Poshta アカウントが必要ですか？ A: はい。my.novaposhta.ua に登録して、API キーを生成する必要があります。

Q: これは Nova Poshta 公式のパッケージですか？ A: いいえ、コミュニティによって保守されているパッケージです。公式 API ドキュメントについては、developers.novaposhta.ua をご覧ください。

Q: 本番環境で使用できますか？ A: はい！このパッケージは、本番環境ですぐに使用でき、エンタープライズ級のエラー処理を備えています。

Q: Nova Poshta API のすべての機能に対応していますか？ A: このパッケージでは、最もよく使われる機能に対応しています。追加機能が必要な場合は、イシューを作成してください。

---

変更履歴

変更履歴の詳細については、CHANGELOG.md をご覧ください。

---

ライセンス

Apache License 2.0。詳細については、LICENSE をご覧ください。

リンク

• MCP レジストリ - 公式レジストリでこのサーバーを探す
• Nova Poshta API ドキュメント
• Model Context Protocol
• MCP SDK

サポート

• イシュー：GitHub Issues
• ディスカッション：GitHub Discussions
• メール：[email protected]

---