Packy Tracking MCP

chính thức

Theo dõi gói hàng đa hãng vận chuyển

Bạn có thể làm gì với Packy Tracking MCP?

Tạo theo dõi — Yêu cầu đăng ký một lô hàng mới qua trackings_create, bao gồm cả việc nhập số theo dõi hàng loạt, để bắt đầu giám sát các bưu kiện.
Liệt kê và truy xuất theo dõi — Sử dụng trackings_list và trackings_get để xem tất cả lô hàng hoặc lấy chi tiết cho một ID theo dõi cụ thể.
Quản lý webhook — Tạo, cập nhật, liệt kê hoặc xóa các điểm cuối webhook bằng webhooks_create, webhooks_update, webhooks_list và webhooks_delete để nhận thông báo sự kiện.
Liệt kê các hãng vận chuyển được hỗ trợ — Truy vấn couriers_list để xem các hãng vận chuyển khả dụng cho tài khoản của bạn.
Tự động phát hiện hãng vận chuyển — Sử dụng courier_detections_create để xác định hãng vận chuyển từ số theo dõi.
Xóa theo dõi — Xóa các bản ghi lô hàng không mong muốn qua trackings_delete để dọn dẹp danh sách theo dõi của bạn.

Tài liệu

Packy Tracking MCP

Packy Tracking MCP kết nối các ứng dụng AI tương thích với Packy Tracking API thông qua Giao thức Ngữ cảnh Mô hình (MCP).

Kho lưu trữ này chứa tài liệu tích hợp công khai và các ví dụ cấu hình. Bản thân triển khai MCP là một dịch vụ lưu trữ; không cần cài đặt máy chủ cục bộ.

Máy chủ MCP hoạt động thay mặt cho tài khoản Packy được kết nối. Nó không cung cấp quyền hạn nào ngoài những quyền có sẵn cho khóa API được chọn trong quá trình ủy quyền OAuth.

Điểm cuối

Điểm cuối MCP sản xuất:

https://mcp.parceltracking.app/mcp

Xác thực

OAuth là phương pháp xác thực được khuyến nghị. Ứng dụng khách mở trang ủy quyền Packy, nơi bạn đăng nhập và chọn một khóa API đang hoạt động. Sau khi bạn phê duyệt quyền truy cập, ứng dụng MCP được kết nối với khóa đó.

Quyền OAuth được máy chủ MCP kiểm tra và không được chuyển tiếp đến API sản phẩm. Các yêu cầu sản phẩm được thực hiện bằng khóa API của tài khoản đã chọn.

Mô hình truy cập

Trong quá trình đồng ý OAuth, người dùng chọn một khóa API đang hoạt động thuộc tài khoản Packy hiện tại.
Ứng dụng MCP được liên kết với khóa đã chọn đó sau khi nhấn Cho phép.
Nhiều ứng dụng MCP có thể được liên kết với cùng một khóa API; mỗi ứng dụng có ủy quyền OAuth riêng.
Ngắt kết nối một ứng dụng chỉ thu hồi quyền truy cập OAuth của ứng dụng đó và không vô hiệu hóa khóa API hoặc ảnh hưởng đến các ứng dụng khác.
Máy chủ MCP xác thực ủy quyền OAuth và trạng thái khóa trước khi chuyển tiếp một hành động đến Packy API.

OAuth với Claude

Trước khi kết nối, hãy đăng nhập vào https://lk.parceltracking.app, tạo khóa API và đảm bảo khóa đang hoạt động.

Mở Claude Settings → Connectors → Add custom connector.
Nhập điểm cuối MCP:
```
https://mcp.parceltracking.app/mcp
```
Giữ xác thực OAuth được bật và cho phép Claude tự động đăng ký một ứng dụng khách.
Đăng nhập vào Packy trong trình duyệt. Một trang Continue authorization ngắn sẽ tự động chuyển hướng; không có gì để nhấp. Liên kết chỉ dùng một lần và hết hạn sau hai phút.
Trên trang Allow access?, chọn khóa API đang hoạt động mà kết nối này sẽ sử dụng và chọn Allow.
Quay lại Claude và xác nhận rằng bộ kết nối đã được kết nối.

Mã thông báo truy cập OAuth có thời hạn ngắn và được làm mới tự động. Nếu luồng thất bại, hãy bắt đầu một nỗ lực kết nối mới từ Claude thay vì mở lại URL ủy quyền trước đó.

OAuth với Codex

codex mcp add packy-tracking-mcp \
  --url https://mcp.parceltracking.app/mcp \
  --oauth-resource https://mcp.parceltracking.app/mcp

Mở URL ủy quyền do Codex in ra, đăng nhập vào Packy, chọn một khóa API đang hoạt động và chọn Allow.

Cursor với khóa API

Thiết lập Cursor được ghi lại sử dụng khóa API. Thêm URL máy chủ và tiêu đề Authorization: Bearer <YOUR_API_KEY> trong mcp.json dự án hoặc người dùng của Cursor, sau đó khởi động lại MCP/đại lý. Xem examples/cursor/mcp.json.

Dự phòng khóa API

Các ứng dụng khách không hỗ trợ MCP OAuth có thể sử dụng trực tiếp khóa API Packy. Khóa API giống với khóa được sử dụng với Packy Tracking API thông thường.

{
  "mcpServers": {
    "packy-tracking-mcp": {
      "url": "https://mcp.parceltracking.app/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Thay thế <YOUR_API_KEY> bằng một khóa đang hoạt động từ tài khoản Packy. Không bao giờ công bố hoặc chia sẻ khóa.

Máy chủ cũng chấp nhận tiêu đề tương đương:

X-API-Key: <YOUR_API_KEY>

Luồng OAuth được khuyến nghị vì khóa được chọn trong Packy và không được sao chép vào cấu hình ứng dụng khách.

Công cụ

Công cụ	Thao tác Tracking API
`trackings_create`	`POST /v1/trackings`
`trackings_list`	`GET /v1/trackings`
`trackings_get`	`GET /v1/trackings/{id}`
`trackings_delete`	`DELETE /v1/trackings/{id}`
`couriers_list`	`GET /v1/couriers`
`courier_detections_create`	`POST /v1/courier-detections`
`webhooks_list`	`GET /v1/webhooks`
`webhooks_create`	`POST /v1/webhooks`
`webhooks_update`	`PATCH /v1/webhooks/{id}`
`webhooks_delete`	`DELETE /v1/webhooks/{id}`

Các thao tác thay đổi dữ liệu đã lưu trữ là trackings_create, trackings_delete, webhooks_create, webhooks_update và webhooks_delete. Chỉ chạy chúng khi bạn thực sự có ý định sửa đổi dữ liệu tài khoản.

Chỉ trackings_create tiêu thụ tín dụng: một tín dụng cho mỗi số theo dõi duy nhất, bao gồm từng số theo dõi trong một lô. Các công cụ chuyển phát, phát hiện, đọc, xóa và webhook không tiêu thụ tín dụng. MCP không bị tính phí riêng so với Tracking API.

Ngắt kết nối và thu hồi

Để dừng một ứng dụng MCP:

Đăng nhập vào tài khoản Packy tại https://lk.parceltracking.app.
Mở Connected applications.
Chọn ứng dụng và chọn Disconnect / Revoke.

Thu hồi một ứng dụng sẽ dừng các yêu cầu mới từ kết nối OAuth đó. Nó không vô hiệu hóa chính khóa API và các ứng dụng khác được kết nối với cùng khóa vẫn độc lập.

Bạn cũng có thể vô hiệu hóa hoặc thay thế khóa API trong phần API keys. Điều này ảnh hưởng đến mọi tích hợp sử dụng khóa đó, bao gồm cả các ứng dụng MCP.

Xác minh dịch vụ

Các điểm cuối kiểm tra trạng thái công khai này không yêu cầu khóa API:

curl -fsS https://mcp.parceltracking.app/health
curl -fsS https://mcp.parceltracking.app/ready

Phản hồi dự kiến:

{"status":"ok"}

{"status":"ok","checks":{"api_gateway":"healthy"}}

/ready cũng xác nhận rằng dịch vụ MCP có thể truy cập cổng API của nó.

Khắc phục sự cố

Nếu không có công cụ nào xuất hiện, hãy kiểm tra điểm cuối, sử dụng tên máy chủ packy-tracking-mcp và khởi động lại ứng dụng khách.
Nếu OAuth không hoàn tất, hãy đăng nhập vào tài khoản Packy dự định, xác nhận rằng tài khoản có khóa API đang hoạt động và bắt đầu một nỗ lực kết nối mới.
Nếu quyền truy cập bị từ chối, hãy xác minh rằng khóa đã chọn đang hoạt động và thuộc tài khoản dự định.
Nếu cần dừng quyền truy cập ngay lập tức, hãy ngắt kết nối ứng dụng trong Connected applications hoặc vô hiệu hóa khóa API.

Liên kết

Trang web Packy: https://packyapp.com
Tài khoản Packy: https://lk.parceltracking.app
Điểm cuối MCP: https://mcp.parceltracking.app/mcp

Hỗ trợ

Đối với các yêu cầu tài khoản và hỗ trợ, hãy gửi email đến wasup@clickor.net.

Đối với các câu hỏi kỹ thuật về Tracking API và tích hợp MCP, hãy tham gia Cộng đồng nhà phát triển Packy trên Discord. Tất cả các tùy chọn liên hệ chính thức đều có tại https://packyapp.com/contacts.

Phạm vi kho lưu trữ

Kho lưu trữ này chỉ chứa tài liệu tích hợp. Nó không chứa mã nguồn Packy API, thông tin xác thực, khóa API, mã thông báo OAuth hoặc cấu hình triển khai.