Shiplogic MCP 服务器

这是一个模型上下文协议（MCP）服务器，提供与Shiplogic运输API的无缝集成。使用MCP SDK和TypeScript构建，以确保类型安全并提升开发体验。

演示

bash

与Claude的示例对话：

用户: "查询从开普敦到约翰内斯堡2.5公斤包裹的运费" Claude: "我将为您查询运费..."

[使用工具: get_shipping_rates] 结果: 经济服务 - R95 (2-3天送达)

用户: "预订经济服务" Claude: "正在创建发货单..."

[使用工具: create_shipment] 结果: 发货单已创建！追踪号: QR4FVL

功能

🚚 获取运费 - 计算两地之间的运输成本
📦 创建发货单 - 预订发货单并自动跟踪
🔍 追踪包裹 - 实时追踪发货状态
❌ 取消发货单 - 在需要时取消预订
➕ 可选服务 - 获取特殊服务的附加费率
📚 地址簿管理 - 存储和管理常用地址

安装

前提条件

Node.js 18+
npm 或 yarn
Shiplogic API 密钥（在 shiplogic.com 获取）

快速开始

克隆并安装： bash git clone https://github.com/jlwainwright/shiplogic-mcp.git cd shiplogic-mcp npm install
配置环境变量： bash cp .env.example .env

编辑 .env 并添加您的 Shiplogic API 密钥
构建服务器： bash npm run build

使用方法

与Claude桌面版配合使用

将以下内容添加到您的Claude桌面配置中：

json { "mcpServers": { "shiplogic": { "command": "node", "args": ["/absolute/path/to/shiplogic-mcp/dist/index.js"], "env": { "SHIPLOGIC_API_KEY": "your_api_key_here" } } } }

通过MCP Inspector测试

使用MCP Inspector测试服务器：

bash npm run inspect

独立运行

直接运行服务器：

bash npm run dev

可用工具

`get_shipping_rates`

计算两个地址之间的运费。

typescript { collection_address: { street_address: string, city: string, code: string, country?: string, type?: "residential" | "business" }, delivery_address: { street_address: string, city: string, code: string, country?: string, type?: "residential" | "business" }, parcels: [{ length: number, // cm width: number, // cm height: number, // cm weight: number, // kg description?: string }], declared_value?: number }

`create_shipment`

创建带有跟踪的新发货单。

typescript { service_level_code: string, // 例如："ECO" collection_address: { /* 同上 / }, delivery_address: { / 同上 / }, parcels: [{ / 同上 */ }], collection_contact: { name: string, mobile_number?: string, email?: string }, delivery_contact: { name: string, mobile_number?: string, email?: string }, customer_reference?: string, mute_notifications?: boolean }

`track_shipment`

通过参考编号追踪发货单。

typescript { tracking_number: string }

`cancel_shipment`

取消现有的发货单。

typescript { tracking_reference: string }

`get_opt_in_rates`

获取可选附加服务的费率。

typescript { collection_address: { /* 地址对象 / }, delivery_address: { / 地址对象 */ } }

`add_address_to_book`

向账户地址簿中添加一个地址。

typescript { account_id: number, address: { street_address: string, city: string, code: string, country?: string, type?: "residential" | "business", company?: string }, name?: string, // 此地址条目的名称 type?: "collection" | "delivery" // 地址类型 }### get_address_book

从账户的地址簿中检索地址。

typescript { account_id: number, type?: "collection" | "delivery" // 可选，按类型过滤 }

`remove_address_from_book`

从账户的地址簿中移除一个地址。

typescript { account_id: number, address_id: number }

配置

环境变量：

变量	描述	是否必需	默认值
`SHIPLOGIC_API_KEY`	您的Shiplogic API密钥	是	-
`SHIPLOGIC_API_URL`	API基础URL	否	`https://api.shiplogic.com`

开发

项目结构

shiplogic-mcp-official/ ├── src/ │ └── index.ts # 主服务器实现 ├── dist/ # 编译后的JavaScript（生成） ├── package.json ├── tsconfig.json ├── .env.example └── README.md

脚本

npm run build - 编译TypeScript
npm run dev - 构建并运行
npm run inspect - 使用MCP Inspector运行

测试

bash

使用MCP Inspector运行

npm run inspect

在另一个终端中测试工具

curl -X POST http://localhost:3000/tools/list

API参考

此服务器与Shiplogic API v2集成。有关详细的API文档，请参阅：

许可证

MIT许可证 - 查看LICENSE文件

贡献

分叉仓库
创建您的功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开Pull Request

支持

🐛 问题：GitHub Issues
📧 电子邮件：your.email@example.com
📚 文档：Wiki
☕ 支持我的工作：Buy Me a Coffee

如果您觉得这个项目有帮助，请考虑支持我的工作。您的支持有助于我投入更多时间进行开源开发，并为社区创造更好的工具。

致谢

使用Model Context Protocol SDK构建
由Shiplogic API提供支持

由Jacques Wainwright用❤️制作

服务配置

[{'mcpServers': {'shiplogic': {'args': ['/absolute/path/to/shiplogic-mcp/dist/index.js'], 'command': 'node', 'env': {'SHIPLOGIC_API_KEY': 'your_api_key_here'}}}}]

来源

来源：github
链接：https://github.com/jlwainwright/shiplogic-mcp

jlwainwright