使用说明

envia-mcp

MCP server + TypeScript client for the Envia.com shipping API.

Quote, label, track, and cancel shipments across 170+ carriers in 18 countries — from AI agents or your own code.

里面有什么

两个出口，一个包装：

导出	导入	用例
MCP 服务器	`envia-mcp`	AI代理（Claude Code、Claude Desktop、Cursor）通过自然语言与Envia交互
客户端库	`envia-mcp/client`	Node.js/TypeScript应用程序使用完全类型安全性直接调用Envia API
类型定义	`envia-mcp/types`	所有API实体的Zod架构和TypeScript类型

支持的国家

美洲

国家	代码	运营商	知名运营商
墨西哥	MX	34	DHL、联邦快递、Estafeta、Paquetexpress、UPS
美国	美国	33	联邦快递、UPS、美国邮政、DHL、Sendle、LSO
哥伦比亚	CO	16	联邦快递，DHL，协调员，服务交付，TCC
阿根廷	AR	12	安德里亚尼，阿根廷邮政，联邦快递，DHL，OCA
巴西	BR	11	科雷奥斯、联邦快递、DHL、Jadlog、Loggi
智利	CL	10	智利快递、智利邮政、联邦快递、DHL、Starken
危地马拉	GT	7	快递货物， DHL， Telomando
加拿大	加利福尼亚州	4	加拿大邮政、Canpar、DHL、Purolator
乌拉圭	UY	3	DHL，特雷戈
秘鲁	PE	1	奥尔瓦

欧洲、亚洲和大洋洲

国家	代码	运营商	知名运营商
西班牙	ES	16	科雷奥斯、DHL、联邦快递、GLS、SEUR、UPS
印度	IN	9	BlueDart、Delhivery、联邦快递、Aramex、Xpressbees
法国	法国	4	Chronopost、Mondial Relay、UPS
意大利	IT	4	意大利邮政、快速公交、InPost、UPS
澳大利亚	澳大利亚	3	Aramex、联邦快递、Sendle
香港	香港	1	联邦快递
日本	日本	1	--
中国	CN	1	--

Envia随着时间的推移增加了运营商和国家。使用 envia_get_carriers 以获取当前列表。

快速开始

作为MCP服务器

服务器连接到 发送沙箱 默认情况下，没有实际费用，可以安全地进行实验。

添加到您的Claude代码配置中(.mcp.json):

{
  "mcpServers": {
    "envia": {
      "command": "node",
      "args": ["/path/to/envia-mcp/dist/index.js"],
      "env": {
        "ENVIA_API_KEY": "your-sandbox-api-key"
      }
    }
  }
}

或者，如果通过npm全局安装：

{
  "mcpServers": {
    "envia": {
      "command": "npx",
      "args": ["envia-mcp"],
      "env": {
        "ENVIA_API_KEY": "your-sandbox-api-key"
      }
    }
  }
}

作为客户图书馆

import { EnviaClient } from 'envia-mcp/client';

// Sandbox (default — safe for testing)
const client = new EnviaClient({
  apiKey: process.env.ENVIA_API_KEY!,
  shippingUrl: 'https://api-test.envia.com',
  queriesUrl: 'https://queries-test.envia.com',
  geocodesUrl: 'https://geocodes.envia.com',
});

// Get rates from all carriers, sorted by price
const quotes = await client.getQuotesAllCarriers(origin, destination, packages);

// Purchase a label (charges your prepaid balance in USD)
const label = await client.createLabel(origin, destination, packages, 'fedex', 'ground');

// Track a shipment
const tracking = await client.trackShipments(['TRACK123']);

MCP工具

服务器暴露 11工具 AI代理可以调用：

工具	描述	破坏性
`envia_quote`	从所有承运商处获取路线的运费
`envia_create_label`	购买运输标签（收取美元余额）	是
`envia_track`	按跟踪号跟踪一个或多个货物
`envia_cancel`	取消发货并要求退款	是
`envia_validate_zipcode`	验证邮政编码并获取地址信息
`envia_get_carriers`	列出一个国家/地区的可用运营商
`envia_get_services`	列出特定运营商的服务
`envia_shipment_history`	获取给定月份/年份的发货历史记录
`envia_schedule_pickup`	安排承运商提货	是
`envia_classify_hscode`	将产品描述分类为海关的HS编码
`envia_lookup_city`	按名称查找城市，获取邮政编码（无身份验证）

所有工具均已归还 标记语言 （用于展示）以及 结构化数据 （用于程序化使用）。

MCP资源

7文档资源为人工智能代理提供了关于Envia API的上下文：

URI	内容
`envia://docs/overview`	API主机、身份验证模型、沙箱与生产
`envia://docs/address-format-mx`	墨西哥地址字段、州代码、colonia映射
`envia://docs/carriers`	34个承运商，服务数量，重量限制
`envia://docs/rate-response`	价格明细、墨西哥比索货币、额外费用
`envia://docs/label-response`	美元货币，永久标签URL，无幂等性
`envia://docs/errors`	错误代码及其处理方法
`envia://docs/international`	国际航运指南：HS编码、商业发票、货币、关税

MCP提示

4个工作流提示引导代理完成多步骤任务：

提示	它做什么
`diagnose-shipment`	调查跟踪状态，识别卡住/失败的货物
`compare-rates`	为所有运营商提供路线报价，比较价格与速度
`verify-address`	验证邮政编码，返回社区和坐标
`prepare-international-shipment`	分步国际货运工作流程

客户端API

这 EnviaClient 类为每个Envia操作提供类型化方法：

import { EnviaClient } from 'envia-mcp/client';

const client = new EnviaClient({ apiKey, shippingUrl, queriesUrl, geocodesUrl });

方法	返回	描述
`getQuotes(origin, dest, packages, carrier)`	`RateQuoteItem[]`	价格从一个承运人
`getQuotesAllCarriers(origin, dest, packages)`	`RateQuoteItem[]`	按价格排序，分为所有运营商
`createLabel(origin, dest, packages, carrier, service)`	`LabelItem`	购买运输标签
`trackShipments(trackingNumbers)`	`TrackingItem[]`	跟踪一个或多个货物
`cancelShipment(carrier, trackingNumber)`	`CancellationItem`	取消并要求退款
`validateZipCode(postalCode, countryCode?)`	`PostalCodeItem[]`	验证邮政编码（无需身份验证）
`getCarriers(countryCode?)`	`Carrier[]`	列出可用的运营商
`getServices(carrier, countryCode?)`	`CarrierService[]`	列出运营商的服务
`getShipmentHistory(month, year)`	`ShipmentHistoryItem[]`	获取一个月的发货历史记录
`schedulePickup(request)`	`PickupResult`	安排承运人提货
`classifyHsCode(description, options?)`	`HsCodeClassification`	将产品分类为HS编码
`generateCommercialInvoice(request)`	`CommercialInvoiceResult`	为海关生成商业发票
`lookupCity(city, countryCode?)`	`CityLookupItem[]`	按名称查找城市，获取邮政编码
`getAvailableCarriers(countryCode?, international?)`	`AvailableCarrier[]`	列出运营商及其可用性详细信息

提交API Gotchas

如果你不小心，会咬你的东西：

Gotcha	详细信息
`phone_code` 不同	引号的国家代码字符串（例如。 `"MX"`)，标签的拨号代码（例如。 `"52"`)
报价为MXN，标签为USD	预付余额以美元计价
标签不是幂等的	重复通话=双重收费，不同的追踪号码
沙盒地理编码已关闭	始终使用生产 `geocodes.envia.com`
每份报价都需要承运人	客户端会自动扇出，但原始API每次调用需要一个运营商
按跟踪号跟踪	`shipmentId` 不可用作跟踪密钥

配置

MCP服务器从环境变量中读取配置：

变量	必填	默认	描述
`ENVIA_API_KEY`	是	-	您的Envia.com API密钥
`ENVIA_SHIPPING_URL`		`https://api-test.envia.com`	运输API基本URL
`ENVIA_QUERIES_URL`		`https://queries-test.envia.com`	查询API基本URL
`ENVIA_GEOCODES_URL`		`https://geocodes.envia.com`	地理代码API基本URL

沙盒vs生产

服务器默认为Envia的沙盒环境。 这是故意的。

这 envia_create_label 该工具购买真正的运输标签——它需要花钱，而且 非幂等 （调用两次会创建两个具有不同跟踪号的标签，并收取两次费用）。AI代理可以在对话中多次触发此工具，并且无法撤消。默认使用沙盒可以防止在开发、测试和实验过程中发生意外充电。

这遵循了行业最佳实践： Supabase MCP 建议“永远不要连接到生产”；条纹分离测试/实时密钥；松弛MCP 默认情况下禁用破坏性操作。

切换到生产

要使用实时Envia API，请将URL环境变量设置为生产主机：

{
  "mcpServers": {
    "envia": {
      "command": "node",
      "args": ["/path/to/envia-mcp/dist/index.js"],
      "env": {
        "ENVIA_API_KEY": "your-production-api-key",
        "ENVIA_SHIPPING_URL": "https://api.envia.com",
        "ENVIA_QUERIES_URL": "https://queries.envia.com"
      }
    }
  }
}

重要提示：

沙箱和生产使用 单独的API密钥 --沙盒密钥在生产环境中不起作用，反之亦然
地理代码(geocodes.envia.com)始终使用生产环境——沙盒地理编码端点已关闭（503）
服务器日志 (sandbox) 或 (PRODUCTION) 在创业时，你总是知道你所处的环境

货币

当 currency 请求中省略了字段。对于期待MXN（或其当地货币）的拉丁美洲用户来说，这是一个常见的困惑来源。官方的 @envia/envia-mcp 服务器继承了这种行为，默默地以美元报价和收费。

我们的实现默认为MXN。 您可以全局覆盖或每次调用覆盖此内容：

// Default: MXN
const client = new EnviaClient({ apiKey, shippingUrl, queriesUrl, geocodesUrl });

// Override globally (e.g., for Colombia)
const client = new EnviaClient({
  apiKey,
  shippingUrl,
  queriesUrl,
  geocodesUrl,
  defaultCurrency: 'COP',
});

// Override per call via the currency parameter
const quotes = await client.getQuotesAllCarriers(origin, destination, packages, {
  currency: 'USD',
});

MCP服务器也默认为MXN。集 ENVIA_DEFAULT_CURRENCY 改变它。

HTTP功能

客户端包括生产级HTTP处理：

SSRF保护 -主机名允许列表仅将请求限制到已知的Envia API域
指数退避重试 --失败的请求最多重试3次，延迟逐渐增加
Retry-After 标头支持 --在重试之前遵守服务器请求的冷却期

与@envia/envia-mcp的比较

Envia在以下位置维护着一个官方MCP服务器 @envia/envia-mcp。以下是一个事实比较：

特性	envia mcp（此项目）	@envia/envia mcp（官方）
Typed TypeScript客户端库	是	否
可配置货币默认值	是（MXN默认值）	否（美元默认值）
Zod响应验证	是	否
结构化MCP输出（数据+Markdown）	是	否
沙盒地理编码回退	是	否
SSRF保护（主机名分配列表）	是	否
使用指数回退重试	是	否
Envia官方品牌	否	是
默认沙盒	是	是
10+MCP工具	是（11）	是

官方服务器中的已知问题：

缺失 settings 标签创建时的对象导致HTTP 400错误
默认为美元而不是墨西哥比索，这对一级市场（墨西哥）来说是出乎意料的

发展

# Clone and install
git clone https://github.com/amak07/envia-mcp.git
cd envia-mcp
npm.cmd install

# Build
npm.cmd run build

# Type check
npm.cmd run typecheck

# Run tests (30 unit tests, mocked API)
npm.cmd run test:run

# Dev mode (watch + restart)
npm.cmd run dev

项目结构

src/
  index.ts          # MCP server entry point (shebang, stdio transport)
  client.ts         # EnviaClient class (standalone, no MCP dependency)
  types.ts          # Zod schemas + TypeScript types for all API entities
  utils.ts          # HTTP helpers, error handling, formatting
  constants.ts      # API URLs, character limits, response format
  tools/
    quote.ts        # envia_quote — fan-out rate quoting
    create-label.ts # envia_create_label — label purchase
    track.ts        # envia_track — shipment tracking
    cancel.ts       # envia_cancel — shipment cancellation
    validate-zipcode.ts  # envia_validate_zipcode — postal code lookup
    get-carriers.ts # envia_get_carriers — carrier directory
    get-services.ts # envia_get_services — service catalog
    index.ts        # Barrel — registerAllTools()
  resources/
    index.ts        # 6 inline documentation resources
  prompts/
    index.ts        # 3 workflow prompts
  client.test.ts    # 30 unit tests (mocked fetch)
tests/
  fixtures/         # Real API response snapshots (JSON)

技术栈

TypeScript 严格模式
MCP-SDK @modelcontextprotocol/sdk 1.27+
黄道带 用于运行时模式验证
本土的 fetch （内置Node.js 18+，无轴）
Vitest 用于单元测试
ESM ("type": "module")

许可证

麻省理工学院

Built for RefaccionesDirect — open-sourced for the MCP community.