Skip to main content
Glama
k3-yamada

mcp-logistics-tracker

by k3-yamada
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

mcp-logistics-tracker — 物流追跡MCPラッパー（参照系・最小PoC）

CI

[既定はモック動作 / AfterShip 経由で実接続も可能] 既定では MockAdapter による決定的モック動作です（APIキー不要）。 AFTERSHIP_API_KEY を設定すると AfterShip（追跡アグリゲーター）経由で ヤマト / 佐川 / 日本郵便に実接続します（外部HTTP通信が発生・詳細は下記）。 国内3社は公開追跡REST APIを持たない（法人契約/申請制）ため、アグリゲーター 経由が実接続の現実解です。

配送業者の追跡番号を渡すと配送状況を返す MCP（Model Context Protocol）サーバーです。 Claude Desktop などの AI エージェントから、自然言語で 「この追跡番号どうなってる？」を実行できるようにします。

型1: 参照系ラッパー。 状態照会・履歴取得のみを行い、更新系（再配達依頼等）は 実装しません。保守リスクを最小化するスコープに絞った最小 PoC です。

何ができるか（提供ツール）

ツール

説明

list_carriers()

対応配送業者（ヤマト運輸 / 佐川急便 / 日本郵便）の一覧を返す

track_shipment(carrier, tracking_number)

現在の配送状況（最新ステータス）を整形テキストで返す

get_tracking_history(carrier, tracking_number)

配送イベント履歴（発送→輸送中→配達完了）を時系列で返す

戻り値はすべて人間可読の日本語整形テキストです（生 JSON は返しません）。 AI エージェントに生 JSON を渡すと余計なキーや推測ノイズを足すため、 そのまま読み上げられる整形済みテキストに固定しています。

出力例（track_shipment）

【ヤマト運輸】追跡番号 123456789012

現在の状況: 配達完了（配達完了 ✓）
最終更新: 2026/07/06 14:03
場所: 世田谷営業所
詳細: 配達が完了しました

Related MCP server: Global Logistics MCP

動作モード: モック / AfterShip 実接続

本 PoC は CarrierAdapter 抽象境界の内側でアダプタを差し替えて動作します。

モード

有効条件

挙動

モック（既定）

APIキー無し

MockAdapter がリアルな偽データを決定的に返す。ネットワーク非依存で完全動作。

AfterShip 実接続

AFTERSHIP_API_KEY 設定

AfterShipAdapter が AfterShip 経由で JP3社に実接続（外部HTTP通信が発生）。

  • 実 API キーは不要。 キーが無くても完全動作します（既定はモック）。

  • ヤマト / 佐川 / 日本郵便は公開追跡REST APIを持たない（法人契約/申請制）ため、 実接続は AfterShip（追跡アグリゲーター）経由で行います。AfterShip は APIキーのみで即利用でき、JP3社を含む多数キャリアに対応します。

  • 直接キャリアAPIキー（YAMATO_API_KEY 等）用の分岐は残していますが、直接接続 アダプタは未実装です（設定すると NotImplementedError で明示的に失敗し、 AfterShip 経由の利用を促します）。

セットアップと実行手順

Python 3.11+ が必要です。以下は uv を使う例です （pip / venv でも同様に可能です）。

cd poc/mcp-logistics-tracker

# 仮想環境を作成
uv venv --python 3.11 .venv

# 依存をインストール（本体 + 開発ツール）
VIRTUAL_ENV=.venv uv pip install -e ".[dev]"

# テスト実行
VIRTUAL_ENV=.venv .venv/bin/python -m pytest --cov=mcp_logistics_tracker

# MCP サーバーを stdio で起動（Claude Desktop 等がこのプロセスを起動する）
VIRTUAL_ENV=.venv .venv/bin/python -m mcp_logistics_tracker.server

pip を使う場合: python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]"

CLI からの手動確認（任意）

MCP クライアント無しでコアロジックだけ試す例:

PYTHONPATH=src .venv/bin/python -c "
from mcp_logistics_tracker import service
print(service.track_shipment_text('yamato', '123456789012'))
print(service.get_tracking_history_text('sagawa', '998877665544'))
"

Claude Desktop への登録方法

Claude Desktop の設定ファイル（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）に以下を追記します。

※ <ABS_PATH> は本PoCディレクトリの絶対パス（例: /Users/yourname/Dev/ai-secretary）に必ず置換してください。そのまま貼り付けると起動に失敗します。

{
  "mcpServers": {
    "logistics-tracker": {
      "command": "<ABS_PATH>/poc/mcp-logistics-tracker/.venv/bin/python",
      "args": ["-m", "mcp_logistics_tracker.server"],
      "env": {
        "PYTHONPATH": "<ABS_PATH>/poc/mcp-logistics-tracker/src"
      }
    }
  }
}

pip install -e . 済みなら PYTHONPATH は不要で、コンソールスクリプト mcp-logistics-tracker を command に指定することもできます。

登録後に Claude Desktop を再起動し、「yamato の 123456789012 を追跡して」のように 話しかけると track_shipment が呼ばれます。

実接続（AfterShip 経由）

AFTERSHIP_API_KEY を設定すると AfterShipAdapter が有効になり、AfterShip Tracking API 経由で JP3社に実接続します。実装は src/mcp_logistics_tracker/adapters.py の AfterShipAdapter、配線は server.py の _build_adapter() にあります。

# .env.example をコピーして値を設定（.env は .gitignore 済み）
cp .env.example .env
# .env の AFTERSHIP_API_KEY に AfterShip のキーを設定
# キー取得: https://organization.automizely.com/api-keys

API キーは必ず環境変数から読みます（os.environ["AFTERSHIP_API_KEY"]）。 ハードコードは禁止です。

環境変数

環境変数名

用途

挙動

AFTERSHIP_API_KEY

AfterShip 経由の実接続（推奨）

設定時に AfterShipAdapter が有効化。JP3社へ実接続（外部HTTP通信が発生）。

YAMATO_API_KEY

直接キャリア接続（未実装）

単独設定時は _build_adapter() が NotImplementedError を送出。

SAGAWA_API_KEY

直接キャリア接続（未実装）

同上。

JAPANPOST_API_KEY

直接キャリア接続（未実装）

同上。

分岐の優先順位: AFTERSHIP_API_KEY あり → AfterShip 実接続 / 無くて直接 キャリアキーあり → NotImplementedError（AfterShip 利用を促す）/ いずれも無し → MockAdapter（既定・モック動作）。

AfterShip API の確認済み仕様

AfterShip 公式ドキュメントで確認した実仕様（2026-07 時点）:

項目

値

ホスト

https://api.aftership.com（HTTPS のみ）

認証

as-api-key ヘッダに API キー

追跡取得

GET /tracking/{version}/trackings/{slug}/{tracking_number}

API バージョン

日付形式（例 2025-07）。constants.AFTERSHIP_API_VERSION でピン留め

レート制限

GET系は 5 req/sec。超過で 429

レスポンス

Body Envelope（meta + data.tracking）

配達完了判定

tracking.tag == "Delivered"（Delivery Statuses enum の9値の1つ）

キャリア slug

ヤマト(国内 TA-Q-BIN)=taqbin-jp / 佐川=sagawa / 日本郵便=japan-post

未確認（防御的実装）: 429 の待機秒ヘッダ名（Retry-After 優先→ x-ratelimit-reset 算出→既定値にフォールバック）、エラー本文の meta.code/meta.message の正確なフィールド名（本実装は HTTP ステータスのみで UpstreamError に変換し本文構造に依存しない）、data のラップキー（tracking 優先・無ければ data 直下）は、公式 SPA ドキュメントで実サンプルまで取得できず、 AfterShip の一般的慣行に基づき防御的にパースしています。ヤマトは総称 slug yamato も併存するため、国内 TA-Q-BIN 前提で taqbin-jp を採用しています。 実キーでの疎通確認は上司判断（本 PoC はHTTPモックでの検証まで）。

レート制限とバックオフ方針

AI エージェントはツールを高頻度で叩くため、上流エラーは構造化して返します。 実アダプタ側では指数バックオフを推奨します:

wait = min(BACKOFF_BASE_SECONDS * 2 ** attempt, cap)   # attempt = 0..BACKOFF_MAX_RETRIES
# RateLimitError.retry_after_seconds が返る場合はそれを優先する

保守に関する免責

  • 本 PoC はモック動作を前提とした実装であり、実キャリア API への接続・ その API バージョン追従保守は含みません。

  • 各社 API の仕様変更（認証方式・エンドポイント・レート制限・レスポンス形式）への 追従は別途保守契約の範囲とします。

  • 追跡データの正確性・可用性は各配送業者の提供する API に依存します。

動作確認済み環境

項目

値

OS

macOS (darwin, Apple Silicon)

Python

3.11.6

mcp パッケージ

1.28.1（FastMCP デコレータ記法 / mcp.server.fastmcp.FastMCP）

トランスポート

stdio（mcp.run(transport="stdio")）

テスト

pytest 9.1.1 — 31 passed（AfterShipAdapter はrespxでHTTPモック・ネットワーク非依存）

Lint / 型

ruff・mypy strict ともにクリーン

mcp の import パス・ツール登録デコレータ（@mcp.tool()）・起動 API は インストール済みパッケージ（1.28.1）の実ソースで確認済みです。 別バージョンでは API が異なる可能性があります。

プロジェクト構成

mcp-logistics-tracker/
├── README.md
├── pyproject.toml          # ruff + mypy + pytest 設定込み
├── .gitignore              # venv / __pycache__ / .env を除外
├── .env.example            # 実APIキーのテンプレート（PoCでは未使用）
├── src/mcp_logistics_tracker/
│   ├── __init__.py
│   ├── constants.py        # 名前付き定数（マジックナンバー排除）
│   ├── models.py           # dataclass モデル + 構造化エラー
│   ├── adapters.py         # CarrierAdapter 抽象境界 + MockAdapter + AfterShipAdapter（実接続）
│   ├── formatting.py       # 整形テキスト生成（人間可読）
│   ├── service.py          # コアロジック（MCP非依存・検証/エラー変換）
│   └── server.py           # FastMCP 配線 + stdio 起動（mcpに依存する唯一の層）
└── tests/
    ├── test_adapters.py
    ├── test_aftership_adapter.py   # AfterShipAdapter（respxでHTTPモック）
    ├── test_formatting.py
    └── test_service.py

コアロジック（adapters / formatting / service / models）は mcp パッケージに 依存しないため、mcp 無しでもテスト可能です。 server.py のみがトランスポート層として mcp に依存します。

Available Tools

3 tools
get_tracking_historyA

指定した配送業者・追跡番号の配送イベント履歴を時系列で返す。

Args: carrier: 配送業者コード（例: yamato / sagawa / japanpost）。 tracking_number: 追跡番号（数字。ハイフン/空白は自動除去）。

ParametersJSON Schema
NameRequiredDescriptionDefault
carrierYes
tracking_numberYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It discloses chronological ordering and automatic removal of hyphens/spaces from tracking numbers. However, it does not mention error handling, rate limits, or read-only behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences for purpose, then a clear Args section. No unnecessary words, front-loaded with main functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values are covered. However, the description lacks references to sibling tools (e.g., 'list_carriers' for valid codes) and does not provide broader context like authentication or when to prefer this tool over 'track_shipment'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description compensates well: it provides carrier examples (yamato, sagawa, japanpost) and explains tracking number formatting (numbers, hyphens/spaces removed). This adds significant value beyond the schema's empty type strings.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns delivery event history for a given carrier and tracking number in chronological order. The verb '返す' (returns) and specific resource '配送イベント履歴' are present, distinguishing it from siblings like 'track_shipment' which may provide a different scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives like 'track_shipment' or 'list_carriers'. There is no mention of prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_carriersA

対応している配送業者（ヤマト運輸・佐川急便・日本郵便）の一覧を返す。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It clearly states the tool returns a list of carriers, which is adequate for a simple read-only operation. No hidden behaviors are expected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence in Japanese, front-loaded with the action and listing the carriers. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with an output schema, the description is fully complete—it states what the tool returns. No additional context is necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. The description does not need to add parameter information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it returns a list of supported carriers and names them (Yamato Transport, Sagawa Express, Japan Post). This is a specific verb+resource with clear scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs siblings like get_tracking_history or track_shipment. The usage context is only implied through naming.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

track_shipmentA

指定した配送業者・追跡番号の現在の配送状況（最新ステータス）を返す。

Args: carrier: 配送業者コード（例: yamato / sagawa / japanpost）。 tracking_number: 追跡番号（数字。ハイフン/空白は自動除去）。

ParametersJSON Schema
NameRequiredDescriptionDefault
carrierYes
tracking_numberYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It mentions that tracking_number hyphens/spaces are auto-removed, a helpful behavioral detail. However, it does not disclose authentication needs, rate limits, or error handling for invalid inputs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise with two sentences: first defines purpose, second details arguments. No wasted words. Could be slightly more structured (e.g., bullet points) but remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists, description need not explain return values. It covers purpose, arg details, and a behavioral note. For a simple lookup tool with 2 required params, this is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description adds meaning. For 'carrier', it lists example values (yamato, sagawa, japanpost). For 'tracking_number', it explains it must be digits and auto-removes hyphens/spaces, which is not evident from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb '返す' (return) and resource '現在の配送状況' (current delivery status). It distinguishes from siblings 'get_tracking_history' and 'list_carriers' by implying it returns the latest status rather than history or carrier list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description indicates when to use (to get current status for a carrier and tracking number) but does not explicitly state when not to use or provide alternatives. Sibling names imply other tools but are not mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedget_tracking_history
    • First observedlist_carriers
    • First observedtrack_shipment
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: listing carriers, fetching current status, and retrieving full history. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (get_tracking_history, list_carriers, track_shipment), making them predictable and readable.

Tool Count5/5

With 3 tools covering listing carriers, current status, and history, the number is well-scoped for a basic logistics tracking server. Each tool earns its place.

Completeness4/5

The tool surface covers the core tracking workflow (carrier discovery, current status, full history). While additional features like batch tracking or validation could be useful, there are no critical gaps.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • shipsaving-mcp

    waka4674
    A
    license
    B
    quality
    D
    maintenance
    An MCP server that wraps the ShipSaving logistics REST API, enabling AI assistants like Claude to perform shipping operations through natural language.
    30
    20
    MIT

  • jp-data-mcp

    kimotostudio
    A
    license
    A
    quality
    B
    maintenance
    MCP server for Japanese public business data, enabling AI agents to validate and look up corporate numbers, search bank/branch codes, and check national holidays. Runs locally with no telemetry; live corporate registry data requires a free NTA app ID.
    8
    MIT

  • geojp-mcp

    55tarkun
    A
    license
    A
    quality
    C
    maintenance
    MCP server for Japanese address and parcel lookup using ReverseGeoJP and ChibanJP APIs, enabling AI agents to convert coordinates to addresses and vice versa.
    4
    79
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/k3-yamada/mcp-logistics-tracker'

If you have feedback or need assistance with the MCP directory API, please join our Discord server