GHN MCP by usefulapi
Quote shipping fees, track orders, and create or cancel shipping orders in GHN.
使うべきか
品質と安全性
A
ツール定義とプロトコルへの準拠に関する自動分析に基づいています。
コンテキストコスト
~2,974トークン数（ツール定義）
~2.8 KB一般的なレスポンスサイズ
注意への影響は大きい（128k コンテキストの 2.32%）
これは、サーバーのツールがモデルのコンテキストに読み込まれるたびに消費されるおおよそのトークン数です。数が多いほど、ほかのタスクに使える注意が減ります。
インストール
ワンクリックインストール
これを `claude_desktop_config.json` ファイルに追加してください:
{
"mcpServers": {
"ghn": {
"url": "https://ghn.usefulapi.io/mcp"
}
}
}リモートエンドポイント
https://ghn.usefulapi.io/mcpstreamable-httpできること
ツール一覧
ツール（9）
🟢 読み取り専用🟡 書き込み🔴 削除⚪ 不明
🟢ghn_list_provinces
List all provinces and cities with their ProvinceID. Use the ProvinceID with ghn_list_districts. Uses the district address model. GHN: GET /master-data/province.
入力スキーマ
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢ghn_list_districts(province_id)
List the districts of one province with DistrictID and service support (SupportType: 0 locked, 1 pickup only, 2 delivery only, 3 both). GHN: GET /master-data/district?province_id=.
入力スキーマ
{
"type": "object",
"properties": {
"province_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Province ID (from ghn_list_provinces)."
}
},
"required": [
"province_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢ghn_list_wards(district_id)
List the wards of one district. Use WardCode (a string) for ghn_calculate_fee and ghn_create_order ward fields. GHN: GET /master-data/ward?district_id=.
入力スキーマ
{
"type": "object",
"properties": {
"district_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "District ID (from ghn_list_districts)."
}
},
"required": [
"district_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢ghn_list_services(from_district_id, to_district_id)
List the delivery services GHN offers on a route for this shop. Returns service_type_id (2 = under 20 kg, 5 = 20 kg or more or multi-parcel). Call it before ghn_calculate_fee. GHN: POST /v2/shipping-order/available-services.
入力スキーマ
{
"type": "object",
"properties": {
"from_district_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Pickup district ID (from ghn_list_districts)."
},
"to_district_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Delivery district ID (from ghn_list_districts)."
}
},
"required": [
"from_district_id",
"to_district_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢ghn_calculate_fee(weight, to_district_id, to_ward_code, service_type_id, from_district_id, ...)
Quote the shipping fee for a parcel to a ward, before creating an order. Quote only: no order is created. GHN: POST /v2/shipping-order/fee.
入力スキーマ
{
"type": "object",
"properties": {
"weight": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 50000,
"description": "Weight in grams (maximum 50000)."
},
"to_district_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Delivery district ID."
},
"to_ward_code": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"description": "Delivery WardCode (from ghn_list_wards)."
},
"service_type_id": {
"anyOf": [
{
"type": "number",
"const": 2
},
{
"type": "number",
"const": 5
}
],
"description": "2 = under 20 kg, 5 = 20 kg or more or multi-parcel."
},
"from_district_id": {
"description": "Pickup district ID. Default: the shop address.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"from_ward_code": {
"description": "Pickup WardCode. Default: the shop address.",
"type": "string",
"minLength": 1,
"maxLength": 20
},
"length": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200,
"description": "Size in cm (maximum 200)."
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200,
"description": "Size in cm (maximum 200)."
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200,
"description": "Size in cm (maximum 200)."
},
"insurance_value": {
"description": "Declared value in VND (maximum 5000000).",
"type": "integer",
"minimum": 0,
"maximum": 5000000
},
"cod_value": {
"description": "Cash on delivery amount in VND (maximum 50000000).",
"type": "integer",
"minimum": 0,
"maximum": 50000000
},
"coupon": {
"description": "Discount coupon code.",
"type": "string",
"maxLength": 100
},
"items": {
"description": "Items. Same shape as ghn_create_order items.",
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "Product name."
},
"code": {
"description": "Product code (SKU).",
"type": "string",
"maxLength": 100
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "Quantity, minimum 1."
},
"price": {
"description": "Unit price in VND.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"length": {
"description": "Length in cm. Required when service_type_id is 5.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200
},
"width": {
"description": "Width in cm. Required when service_type_id is 5.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200
},
"height": {
"description": "Height in cm. Required when service_type_id is 5.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200
},
"weight": {
"description": "Weight in grams. Required when service_type_id is 5.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 50000
}
},
"required": [
"name",
"quantity"
]
}
}
},
"required": [
"weight",
"to_district_id",
"to_ward_code",
"service_type_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢ghn_get_order(order_code)
Get the full details of one shipping order by its GHN tracking code: status, parties, COD, fees and items. GHN: GET /v2/shipping-order/detail?order_code=.
入力スキーマ
{
"type": "object",
"properties": {
"order_code": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "GHN tracking code, e.g. LADFYR (returned by ghn_create_order)."
}
},
"required": [
"order_code"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢ghn_get_order_by_client_code(client_order_code)
Get the full details of one shipping order by your own client_order_code instead of the GHN tracking code. GHN: GET /v2/shipping-order/detail-by-client-code?client_order_code=.
入力スキーマ
{
"type": "object",
"properties": {
"client_order_code": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Your own order code (the client_order_code set when the order was created)."
}
},
"required": [
"client_order_code"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴ghn_create_order(client_order_code, to_name, to_phone, to_address, to_ward_name, ...)
CREATES A REAL SHIPPING ORDER: GHN picks up and delivers the parcel and can charge the shop or collect cash on delivery (COD) from the recipient. Call only after the user explicitly confirms the recipient, the parcel and the fee in this chat (use ghn_calculate_fee first). client_order_code is required: a retry with the same code returns the first order and creates no duplicate. Set to_district_name when is_new_to_address is false. Send content or items. GHN: POST /v2/shipping-order/create.
入力スキーマ
{
"type": "object",
"properties": {
"client_order_code": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Your unique order code for this shop. Retries with the same code are safe."
},
"to_name": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "Recipient name."
},
"to_phone": {
"type": "string",
"minLength": 6,
"maxLength": 20,
"description": "Recipient phone."
},
"to_address": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "Recipient full address."
},
"to_ward_name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Recipient ward name (from ghn_list_wards or the new province model)."
},
"to_district_name": {
"description": "Recipient district name. Required when is_new_to_address is false.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"to_province_name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Recipient province or city name."
},
"is_new_to_address": {
"description": "true for the 2025 address model (ward and province only). Default false.",
"type": "boolean"
},
"weight": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 50000,
"description": "Total weight in grams."
},
"length": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200,
"description": "Size in cm (maximum 200)."
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200,
"description": "Size in cm (maximum 200)."
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200,
"description": "Size in cm (maximum 200)."
},
"service_type_id": {
"anyOf": [
{
"type": "number",
"const": 2
},
{
"type": "number",
"const": 5
}
],
"description": "2 = under 20 kg, 5 = 20 kg or more or multi-parcel (then items with sizes are required)."
},
"payment_type_id": {
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
}
],
"description": "Who pays the shipping fee: 1 = the shop, 2 = the recipient."
},
"required_note": {
"type": "string",
"enum": [
"KHONGCHOXEMHANG",
"CHOXEMHANGKHONGTHU",
"CHOTHUHANG"
],
"description": "Delivery rule: KHONGCHOXEMHANG = no inspection, CHOXEMHANGKHONGTHU = inspect but do not try, CHOTHUHANG = inspect and try."
},
"content": {
"description": "Goods description. Send content or items.",
"type": "string",
"maxLength": 2000
},
"items": {
"description": "Items. Required when service_type_id is 5.",
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "Product name."
},
"code": {
"description": "Product code (SKU).",
"type": "string",
"maxLength": 100
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "Quantity, minimum 1."
},
"price": {
"description": "Unit price in VND.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"length": {
"description": "Length in cm. Required when service_type_id is 5.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200
},
"width": {
"description": "Width in cm. Required when service_type_id is 5.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200
},
"height": {
"description": "Height in cm. Required when service_type_id is 5.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 200
},
"weight": {
"description": "Weight in grams. Required when service_type_id is 5.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 50000
}
},
"required": [
"name",
"quantity"
]
}
},
"cod_amount": {
"description": "Cash on delivery to collect from the recipient, in VND. Default 0.",
"type": "integer",
"minimum": 0,
"maximum": 50000000
},
"insurance_value": {
"description": "Declared insurance value in VND (maximum 5000000). Default 0.",
"type": "integer",
"minimum": 0,
"maximum": 5000000
},
"note": {
"description": "Note for the shipper.",
"type": "string",
"maxLength": 5000
}
},
"required": [
"client_order_code",
"to_name",
"to_phone",
"to_address",
"to_ward_name",
"to_province_name",
"weight",
"length",
"width",
"height",
"service_type_id",
"payment_type_id",
"required_note"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴ghn_cancel_orders(order_codes, reason_code, reason)
CANCELS REAL SHIPPING ORDERS. The batch is all-or-nothing: one unknown or foreign order code cancels nothing. Call only after the user explicitly confirms the order codes. An order that can no longer be cancelled returns result false. GHN: POST /v2/switch-status/cancel.
入力スキーマ
{
"type": "object",
"properties": {
"order_codes": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "GHN tracking code, e.g. LADFYR (returned by ghn_create_order)."
},
"description": "GHN tracking codes to cancel, in one batch."
},
"reason_code": {
"description": "GHN-CO001 = pickup taking too long, GHN-CO002 = out of stock, GHN-CO003 = recipient no longer wants it, GHN-CANCEL-OTHER = other.",
"type": "string",
"enum": [
"GHN-CO001",
"GHN-CO002",
"GHN-CO003",
"GHN-CANCEL-OTHER"
]
},
"reason": {
"description": "Free-text reason for every order in the batch.",
"type": "string",
"maxLength": 500
}
},
"required": [
"order_codes"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}コミュニティ
エビデンス
最近の観測
検証済みバージョンは記録されていませんツール 9 件