Envia MCP Server

@send/send-mcp

](https://www.npmjs.com/package/@envia/envia-mcp)   ](https://nodejs.org)

MCP服务器 发送 运输API。报价率、创建标签、跟踪包裹、安排提货、管理电子商务订单等等——直接从您的人工智能助手完成。

部署模型（v1）： 此MCP旨在运行 嵌入在Envia门户的身份验证会话中HTTP传输旨在用于门户后端的服务器到服务器调用，而不是用于公共多租户访问。stdio传输是IDE集成（Claude Desktop、Cursor、VS Code）的标准路径，支持每个请求 api_key 覆盖本地开发人员工作流。看 运输方式 和 认证 在......下面

快速启动

# Run with npx (no install needed)
npx @envia/envia-mcp

通过环境变量设置您的API密钥或将其按要求传递（请参阅 认证):

export ENVIA_API_KEY="your_jwt_token_here"

# Optional: use production (default is sandbox)
# export ENVIA_ENVIRONMENT="production"

从获取API密钥 开发人员→API访问 在您的仪表板中：

• 沙箱： shipping-test.envia.com/settings/developers · 注册
• 生产： shipping.envia.com/settings/developers · 注册

IDE设置

克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "envia": {
      "command": "npx",
      "args": ["@envia/envia-mcp"],
      "env": {
        "ENVIA_API_KEY": "your_jwt_token_here"
      }
    }
  }
}

光标

添加 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "envia": {
      "command": "npx",
      "args": ["@envia/envia-mcp"],
      "env": {
        "ENVIA_API_KEY": "your_jwt_token_here"
      }
    }
  }
}

VS Code

添加 .vscode/mcp.json 在项目根目录中：

{
  "servers": {
    "envia": {
      "type": "stdio",
      "command": "npx",
      "args": ["@envia/envia-mcp"],
      "env": {
        "ENVIA_API_KEY": "your_jwt_token_here"
      }
    }
  }
}

运输方式

服务器支持两种传输模式，由 MCP_TRANSPORT 环境变量：

认证

• HTTP/门户嵌入式（v1）： MCP使用服务器级别 ENVIA_API_KEY 对于每一个请求。根据请求 api_key 模式接受重写以与stdio主机兼容，但门户嵌入式部署预计将依赖于服务器密钥和网络级隔离。HTTP表面的硬化（源允许列表、共享密钥头）作为Sprint 4项目进行跟踪。
• stdio / IDE ： 集 ENVIA_API_KEY 在MCP主机配置中。经过 api_key 多帐户本地工作流支持内联每个工具调用。

# HTTP mode (default)
npx @envia/envia-mcp

# stdio mode
MCP_TRANSPORT=stdio npx @envia/envia-mcp

# Or use the convenience script
npm run start:stdio

聊天演示（仅限开发）

HTTP模式在以下位置提供浏览器聊天UI / (src/chat/index.html).此UI 是一个 开发和本地测试工具，而不是生产流程：

• 用户粘贴他们的Anthropic或OpenAI API密钥和他们的Envia令牌

直接输入浏览器。

• 消息从浏览器发送 直接 LLM提供者

（Anthropic使用 anthropic-dangerous-direct-browser-access: true 官方SDK标记为生产不安全的标头）。

• 输入到UI中的密钥和令牌对浏览器DevTools可见，

扩展以及任何有权访问主机的人。

不要将生产凭据粘贴到聊天UI中。 生产 模式是门户嵌入式代理，其中Envia门户后端 通过HTTP调用MCP，并使用服务器端密钥调用Anthropic。

如果您部署了MCP并且不需要演示UI，请禁用静态 服务路线 src/chat/ 被跟踪为Sprint 4项目。

可用工具

认证

每个工具都接受 api_key 覆盖服务器级别的参数 ENVIA_API_KEY这允许多租户设置，其中不同的用户根据请求提供自己的凭据。

• 所需工具 (9) — api_key 必须提供。这些操作基于用户特定的数据（费率、标签、订单、提货、历史）。
• 可选工具 (3) — api_key 是可选的。 envia_validate_address, envia_track_package，以及 envia_classify_hscode 使用服务器默认设置，但接受覆盖。

当没有提供覆盖时，服务器将回退到 ENVIA_API_KEY 从环境。

附加服务

两者 envia_quote_shipment 和 envia_create_shipment 支持可选的附加服务，如保险、货到付款和签名要求：

• additional_services --数组 { service, amount? } 物体。使用 envia_list_additional_services 以发现路线的可用服务。
• insurance_type --保险快捷方式： "envia_insurance", "insurance" （载体原生，CO/BR），或 "high_value_protection"每次装运只允许一种类型。
• cash_on_delivery_amount --自动添加 cash_on_delivery 指定收款金额的服务。

速率响应显示应用了哪些服务，并警告运营商忽略的任何服务。

地址自动解析

两者 envia_quote_shipment 和 envia_create_shipment 使用Envia地理编码API从邮政编码中自动解析城市、州和地区（colonia）。哥伦比亚DANE代码也会自动翻译。仅在需要重写时提供显式值。

对于 MX地址，地区（colonia/社区）尤为重要——一些运营商在这个级别验证可用性。该工具会自动从邮政编码的第一个郊区解析它，但您可以提供 origin_district / destination_district 当客户明确知道他们的特定colonia时。

envia_create_shipment——双模

• 手动模式 --直接提供地址、包裹详细信息、承运商和服务。对于国际货运 items 需要包含海关数据（数量、价格、HS编码）的数组。
• 电子商务模式 --通过A order_identifier 该工具在一个步骤中获取订单、提取地址/包裹/承运人、解析打印设置并生成标签。

动态地址验证

在创建任何标签之前， envia_create_shipment 根据国家的通用形式规则（从Envia API获取）验证源地址和目的地地址。每个国家都定义了哪些地址字段是必需的，例如，BR要求 identificationNumber （CPF/CNPJ），而其他国家可能要求 district 或 reference。缺少的字段将使用要提供的确切工具参数名称进行报告。

这 envia_validate_address 该工具还会显示这些必填字段，因此代理可以在调用之前主动发现所需的内容 envia_create_shipment.

巴西DCe预授权

对于BR到BR的国内运输，巴西法规要求在生成标签之前获得SEFAZ的Declaracao de Conteudo Eletronica（DCe）授权。 envia_create_shipment 自动处理此问题：

1. 验证 items 配备有 productCode （NCM代码）用于每个项目
2. 验证起点和终点是否都有 identificationNumber （CPF或CNPJ）
3. 调用DCe授权端点以获得SEFAZ批准
4. 注入结果 xmlData 进入包装有效载荷

如果您已经拥有DCe授权数据（例如，来自外部系统），请通过 xml_data 参数跳过自动授权。

国家特定地址处理

对于MX和BR地址，外部编号(number)作为单独的字段发送--提供 origin_number / destination_number 明确地。对于所有其他国家来说，这个数字是 street 现场和 number 是空的。这是由地址构建器自动处理的。

示例对话

国内运输（墨西哥）

You: Ship a 2kg box (30x20x15cm) from postal code 64000 in Monterrey
     to 03100 in Mexico City. Compare DHL and Estafeta rates.

AI:  [validates both postal codes with envia_validate_address]
     [fetches rates with envia_quote_shipment for dhl,estafeta]

     Here are your options:
       DHL Economy:    $185.20 MXN — 3-5 business days
       Estafeta Express: $210.00 MXN — 1-2 business days

     Would you like me to create a label with one of these?

You: Yes, go with DHL Economy.

AI:  [creates label with envia_create_shipment]

     Label created!
       Tracking: 7520610403
       Label PDF: https://...
       Price: $185.20 MXN

国际货运

You: Ship a leather handbag worth $299 USD from Monterrey (66612)
     to McAllen TX (78572) via DHL International Express.

AI:  [classifies HS code with envia_classify_hscode → 4202.21]
     [creates label with envia_create_shipment, including items array]

     Label created!
       Tracking: 1234567890
       Label PDF: https://...
       Carrier: DHL / int_express

有保险和货到付款的装运

You: Quote a 3kg package from Bogota DC to Medellin ANT with Envia insurance
     for $500,000 COP and collect $200,000 cash on delivery.

AI:  [lists services with envia_list_additional_services for CO]
     [fetches rates with envia_quote_shipment, insurance_type="envia_insurance",
      declared_value=500000, cash_on_delivery_amount=200000]

     Found 4 rates:
       Servientrega / express: $18,500 COP — 1-2 days
         Base: $12,000 | Insurance: $2,500 | COD commission: $4,000
       Coordinadora / standard: $15,200 COP — 2-3 days
         Base: $10,200 | Insurance: $2,000 | COD commission: $3,000
         ⚠ Requested service(s) not applied: envia_insurance
       ...

巴西国内（DCe）

You: Ship a Smart TV AIWA 32" worth R$800 from São Paulo (01310-100)
     to Rio de Janeiro (20040-020) via Correios SEDEX.
     Sender CPF: 123.456.789-09, recipient CPF: 987.654.321-00.

AI:  [validates addresses with envia_validate_address — confirms BR
      requires identificationNumber, address fields complete]
     [creates label with envia_create_shipment, including items with
      productCode "8528.72.00" and both identification numbers]

     DCe authorized by SEFAZ!
     Label created!
       Tracking: BR123456789
       Label PDF: https://...
       Carrier: correios / sedex
       DCe Key: 35260412345678900199...

电子商务订单（一步到位）

You: Create a label for order #1062.

AI:  [fetches order with envia_create_shipment(order_identifier="1062")]

     Label created!
       Tracking: 9876543210
       Label PDF: https://...
       Carrier: fedex / ground

建筑

src/
├── index.ts               # Entry point — transport selection (stdio / HTTP)
├── config.ts              # Environment configuration
├── builders/              # Domain-specific payload constructors
│   ├── address.ts         #   Address objects for rate and generate APIs
│   ├── package.ts         #   Package objects with items and additional services
│   ├── additional-service.ts  # Merge insurance, COD, and explicit services
│   └── ecommerce.ts       #   Ecommerce metadata section
├── services/              # Business logic and API orchestration
│   ├── ecommerce-order.ts #   Fetch and transform V4 orders
│   ├── carrier.ts         #   Carrier list fetching
│   ├── additional-service.ts  # Query available additional services
│   ├── dce.ts             #   BR DCe authorization with SEFAZ
│   └── generic-form.ts    #   Country-specific address field validation
├── tools/                 # MCP tool registrations (one file per tool)
├── types/                 # TypeScript interfaces
│   ├── carriers-api.ts    #   Carriers API payload types (source of truth)
│   └── ecommerce-order.ts #   V4 order response types
├── utils/                 # Shared utilities
│   ├── api-client.ts      #   HTTP client with auth, retries, and resolveClient
│   ├── address-resolver.ts#   Geocoding and DANE code resolution
│   ├── print-settings.ts  #   Carrier print format/size lookup
│   ├── mcp-response.ts    #   MCP text response helper
│   ├── schemas.ts         #   Shared Zod schemas (country, carrier, api_key)
│   └── validators.ts      #   Input validation helpers
├── resources/             # MCP resources (API docs)
└── chat/                  # Browser chat UI for HTTP mode

环境变量

发展

git clone https://github.com/envia-ep/envia-mcp-server.git
cd envia-mcp-server
npm install
npm run build
npm test

许可证

麻省理工学院