MéxicoAPI

mexicoapi-mcp

此 README 跟随 main 分支；标注为「从 0.2.0 起」的内容不在 npm 的 0.1.0 版本中，该版本的 README 可在 npm 查看。

提供墨西哥官方参考数据的 MCP（Model Context Protocol）服务，让助手查询已发布的数据，而非凭空编造：州和市镇、银行和 CLABE、RFC、CURP 和 NSS、FIX 汇率、UDIS、非工作日和工作日、UMA、最低工资、ISR 税率和邮政编码。

• 在你的设备上运行，并通过 stdio 与客户端通信。
• 只读：任何工具都不会写入、删除或发送任意请求。
• 会过期的数据（FIX、UDIS、日历和常量）会向 MéxicoAPI 公共 API 请求；如果 API 无响应，则使用 mexicoapi 包中的数据；其他数据始终来自该包。设置 MEXICOAPI_SIN_RED=1 后可离线运行。每个结果都会附带其官方来源、截止日期和数据来源。

要求

Node 22.13 或更高版本。

配置

在客户端的 MCP 服务配置中：

{
  "mcpServers": {
    "mexicoapi": {
      "command": "npx",
      "args": ["-y", "mexicoapi-mcp"]
    }
  }
}

不同客户端的配置位置：

客户端	位置	根键
Claude Desktop	claude_desktop_config.json（Settings > Developer > Edit Config）：Windows 上为 %APPDATA%\Claude\，macOS 上为 ~/Library/Application Support/Claude/	mcpServers
Claude Code	claude mcp add mexicoapi -- npx -y mexicoapi-mcp；使用 --scope project 时，配置位于项目根目录下的 .mcp.json	mcpServers
Cursor	项目中的 .cursor/mcp.json，或供所有项目使用的 ~/.cursor/mcp.json	mcpServers
VS Code	项目中的 .vscode/mcp.json	servers，不是 mcpServers

VS Code 使用不同的根键，并要求指定服务类型：

{
  "servers": {
    "mexicoapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mexicoapi-mcp"]
    }
  }
}

在 Windows 上，如果客户端找不到 npx，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "mexicoapi-mcp"]；在 Claude Code 中，使用 claude mcp add mexicoapi -- cmd /c npx -y mexicoapi-mcp。

如果不使用 npx，而是已安装软件包（npm install mexicoapi-mcp）或从代码仓库构建（pnpm -r build 会生成 packages/mcp/dist/index.js），请将 node 指向服务文件的绝对路径（Windows 上写作 C:/ruta/a/...）：

{
  "mcpServers": {
    "mexicoapi": {
      "command": "node",
      "args": ["/ruta/a/node_modules/mexicoapi-mcp/dist/index.js"]
    }
  }
}

API：MEXICOAPI_BASE 和 MEXICOAPI_SIN_RED（可选）

会过期的数据工具（FIX、UDIS、非工作日和工作日、UMA、最低工资和 ISR）会查询 MéxicoAPI 公共 API（https://mexicoapi.dagel4k.workers.dev）；如果 API 无响应，则使用 mexicoapi 包中的数据并发出警告。其他工具绝不会使用网络。

• MEXICOAPI_BASE 用于更改 API 地址，例如指向你自己的部署或 wrangler dev 本地 API。从 0.2.0 起，http:// 地址仅接受 localhost、127.0.0.1 或 [::1]；其他主机请使用 https://。
• MEXICOAPI_SIN_RED=1 会让服务仅使用软件包中的数据响应所有请求，不使用网络，即使设置了 MEXICOAPI_BASE 也一样。从 0.2.0 起，也接受 true、yes、si 或 on；设置为 0、false、no、off 或留空时则会查询 API，不区分大小写。

{
  "mcpServers": {
    "mexicoapi": {
      "command": "npx",
      "args": ["-y", "mexicoapi-mcp"],
      "env": { "MEXICOAPI_BASE": "http://127.0.0.1:8787" }
    }
  }
}

如果地址无效（包含凭据、查询参数或片段；从 0.2.0 起也包括指向其他主机的 http:// 地址），或者 MEXICOAPI_SIN_RED 的值不符合要求（从 0.2.0 起），服务将无法启动：以退出码 2 退出，并在 stderr 中显示一条不会重复该值的消息。

工具

工具	功能	网络
buscar_municipio	按名称在 INEGI 目录中搜索市镇和自治市	否
municipio	根据地理统计代码（cvegeo）查询一个市镇	否
estados（自 0.2.0 起）	查询 32 个联邦实体及其代码（cve_ent）、名称和缩写	否
municipios_de_estado（自 0.2.0 起）	查询一个州的所有市镇和自治市（地理统计代码 cvegeo 和名称）及总数；州可通过代码（cve_ent）或名称指定	否
validar_clabe	验证 CLABE（校验位和银行）	否
banco_por_codigo	根据 3 位代码查询 SPEI 银行或参与方	否
validar_rfc	验证 RFC 格式；会检查同质码的校验位，但如果不匹配，只会发出提示，不会将 RFC 标记为无效	否
validar_curp	验证 CURP 格式和校验位	否
validar_nss	验证 IMSS NSS	否
tipo_de_cambio_fix	查询某日公布的 FIX、适用于某笔交易的 FIX，或最新 FIX	是，但设置 MEXICOAPI_SIN_RED=1 时除外
udis	查询某日的 UDI 值	是，但设置 MEXICOAPI_SIN_RED=1 时除外
dias_inhabiles	根据 LFT、CNBV 或 SAT 查询某年的非工作日	是，但设置 MEXICOAPI_SIN_RED=1 时除外
sumar_dias_habiles	根据 LFT、CNBV（银行）或 SAT 日历，从某日期起增加工作日数，并提示哪些情况不会扣除：使用 LFT 时，不扣除节假日和第 715 条规定的停工日；使用 SAT 和 declaraciones_pagos 时，也不考虑 CFF 第 12 条规定的延期；自 0.2.0 起，如果结果落在已公布的假期内，也会提示	是，但设置 MEXICOAPI_SIN_RED=1 时除外
constantes	查询 UMA、最低工资和 ISR 税率	是，但设置 MEXICOAPI_SIN_RED=1 时除外
codigo_postal	根据邮政编码查询州、市镇和居民区	否（读取本地缓存）

所有工具都声明了 readOnlyHint: true、严格的输入架构和 outputSchema。只有使用网络的工具（也就是数据会过期的工具）的 openWorldHint 才为 true，但设置 MEXICOAPI_SIN_RED=1 时除外。验证器会检查格式和校验位，并在各自的 nota 中说明（自 0.2.0 起）；它们不会确认账户、RFC、CURP 或 NSS 是否真实存在。validar_clabe 始终会根据目录核验银行（banco_revisado: true，自 0.2.0 起）。

每项结果包含什么

每项结果都包含西班牙语文本和 structuredContent，后者符合工具的 outputSchema：

{
  "datos": { "fecha": "2026-10-01", "valor": "8.836029" },
  "as_of": "2026-10-18",
  "fuente": { "nombre": "Diario Oficial de la Federación (SIDOF): valor de la unidad de inversión (UDIS)", "url": "https://sidof.segob.gob.mx/" },
  "fuentes": [{ "nombre": "Diario Oficial de la Federación (SIDOF): valor de la unidad de inversión (UDIS)", "url": "https://sidof.segob.gob.mx/" }],
  "origen": "paquete",
  "advertencias": [],
  "avisos": []
}

• datos：请求的值及其自身日期（即该值的日期）。
• as_of：数据集的截止日期，即最近一次导致数据集变更的更新日期。它不是该值的日期。RFC、CURP 和 NSS 的值为 null（它们是算法，而非已发布的数据）；如果墨西哥邮政没有提供日期，codigo_postal 的值也为 null，此时 descargado 会标明目录的下载日期。
• fuente 和 fuentes：包含 URL 的官方发布来源，可用于引用。fuente 是 fuentes 中的第一个来源。
• origen：如果 API（公共 API 或 MEXICOAPI_BASE 指定的 API）有响应，则为 api；如果数据和规则来自 mexicoapi 包，则为 paquete；在 codigo_postal 中则为 cache_local。
• advertencias：需要告知提问者的内容，例如 API 出错，或日历可能不完整。
• avisos（自 0.2.0 起）：与 advertencias 相同，顺序也相同；每条提示都带有稳定代码（{ "codigo": "lft-art-715", "texto": "…" }），供程序在不读取文本的情况下作出判断。sumar_dias_habiles 也会返回 datos.avisos。代码见 API 指南。结果文本中只包含提示内容。 工具接收和返回的日期（publicado、operacion、fecha、desde）均为墨西哥城（America/Mexico_City）的日期。服务端不会判断今天是几号：如果要查询今天付款适用的 FIX，助手必须使用该时区的今天日期请求 operacion。墨西哥城时间 18:00 至 24:00 期间，UTC 已是次日；使用该日期查询，返回结果可能是另一天的 FIX，这并不表示出错。tipo_de_cambio_fix 的描述会告诉助手这一点（自 0.2.0 起）。

离线运行（MEXICOAPI_SIN_RED=1）时，未指定日期的 FIX（最近一次发布）以及距软件包最后一条数据不超过 7 天的 FIX 或 UDIS 查询，都会提示近期发布的数据可能缺失。这与 mexicoapi 客户端的阈值（DIAS_DATOS_RECIENTES）相同；该阈值按最后一条数据到今天的天数计算，因此一次响应可能同时包含这两条警告。软件包中最近一条 FIX 数据也会显示客户端的相同提示（AVISO_SIN_API）；自 0.2.0 起，同一条响应只会显示一次。日历和常量不需要此提示：超出软件包覆盖范围时会返回错误，绝不会返回较早的值。

工具出错（参数无效、数据不存在、日历未覆盖相应期间，或 API 响应格式与预期不符）时，结果会包含 isError: true 和说明出错原因的文本。文本以方括号括起的问题类型开头，与 API 使用的类型相同：[parametro-invalido] 和 [parametro-faltante]（需要修正调用）、[no-encontrado]（数据不存在）、[dato-no-disponible]（尚未发布或加载，之后可能会有）、[calendario-incompleto]、[https-requerido]（API 只接受 https://）、[demasiadas-peticiones] 和 [error-interno]（出现意外响应）。例如：[no-encontrado] No existe el banco 999.。此外，自 0.2.0 起还会出现 [sin-conexion]，这不是 API 的错误类型：服务端无法连接 API（网络断开或超时），且软件包中的数据不足以作答，因此该数据可能存在，建议稍后重试。没有软件包数据可用时，或者软件包也没有相应数据，因为数据尚未发布或不在覆盖范围内（dato-no-disponible、calendario-incompleto），都会返回此错误类型；此时文本会接着说明软件包返回的内容：[sin-conexion] No se pudo conectar con la API. Con los datos del paquete: El FIX del … no está en los datos del paquete; …。即使 API 无响应，软件包给出的确定结果也不会改变：某天没有发布 FIX，仍会返回 [no-encontrado]；参数无效，仍会返回 [parametro-invalido]。

数据更新情况

mexicoapi 软件包中的数据截止日期取决于其版本。npx 会缓存已安装的内容，不会更新版本未变的软件包依赖，因此已经使用过该服务端的用户不会自动获得新版 mexicoapi。所以，每次发布 mexicoapi 新版本后，都会发布一个要求使用该版本或更高版本的 mexicoapi-mcp 版本：npx 会检测到有新版本，并安装包含新数据的版本。as_of 和警告始终会说明每条数据的日期。

邮政编码（SEPOMEX）

邮政编码目录属于墨西哥邮政，不得再分发，因此此软件包和 mexicoapi 都不包含该目录。要让 codigo_postal 正常工作，请在你的设备上下载一次：

npx mexicoapi sepomex sync

该命令会显示墨西哥邮政的使用声明，并将目录保存到本地缓存（Windows 上为 %LOCALAPPDATA%\mexicoapi\sepomex，其他系统上为 $XDG_CACHE_HOME/mexicoapi/sepomex 或 ~/.cache/mexicoapi/sepomex）。服务只读取该缓存。没有目录时，codigo_postal 会返回错误，并提示用于下载的命令。每个结果都会附带使用声明，你对这些数据的使用也受墨西哥邮政条款约束。详情请参阅 mexicoapi 的 README。

隐私

• 不收集遥测数据。
• 服务不会将 CLABE、RFC、CURP 或 NSS 发送到任何 API：它会在你的设备上验证这些信息，包括查询 API 时。
• 这仅适用于服务。助手的宿主（运行该服务的应用）会像处理对话的其他内容一样，将每个工具的参数和结果发送给模型提供商。如果某项数据不应离开你的设备，就不要提供给助手。
• 服务只会与 MexicoAPI 公共 API 或 MEXICOAPI_BASE 指定的地址通信，且仅用于会过期的数据工具。设置 MEXICOAPI_SIN_RED=1 后不会使用网络。
• 日志写入 stderr，绝不会包含工具参数或 MEXICOAPI_BASE 的地址。

协议

• stdio 传输：每行一条 JSON-RPC 消息。
• MCP 版本：2025-11-25、2025-06-18、2025-03-26 和 2024-11-05。客户端请求其他版本时，服务会以 2025-11-25 响应。
• 功能：仅支持 tools，不支持 listChanged。
• 已使用官方 TypeScript MCP 客户端进行测试，该客户端会列出工具、调用工具，并根据其 outputSchema 验证每个结果。

许可证

代码采用 MIT 许可证。数据不属于本项目：仍受发布机构（INEGI、Banxico、DOF、CNBV、SAT、CONASAMI）的条款约束，每个结果都会注明来源。详情请参阅 DATA_LICENSE.md。