Envia MCP

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.

______________________________________________________________________

里面有什么

两个出口，一个包装：

支持的国家

美洲

欧洲、亚洲和大洋洲

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代理可以调用：

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

MCP资源

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

MCP提示

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

______________________________________________________________________

客户端API

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

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

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

______________________________________________________________________

提交API Gotchas

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

______________________________________________________________________

配置

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

沙盒vs生产

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

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

切换到生产

要使用实时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。以下是一个事实比较：

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

• 缺失 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.