MéxicoAPI

mexicoapi-mcp

この README は main に対応しています。「0.2.0 以降」と記載された内容は npm の 0.1.0 には含まれていません。0.1.0 の README は npm で確認できます。

メキシコの公式な参照データを提供する MCP（Model Context Protocol）サーバーです。アシスタントがデータを作り上げずに、公開されている情報を参照できるようにします。州と市町村、銀行と CLABE、RFC、CURP と NSS、FIX 為替レート、UDIS、休日と営業日、UMA、最低賃金、ISR 税率、郵便番号に対応しています。

• お使いのコンピューター上で動作し、stdio 経由でクライアントと通信します。
• 読み取り専用です。どのツールもデータの書き込み、削除、任意のリクエストを行いません。
• 有効期限のあるデータ（FIX、UDIS、カレンダー、定数）は MéxicoAPI の公開 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	mcpServers ではなく servers

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）に問い合わせます。応答がない場合はパッケージ mexicoapi のデータを使用し、その旨を通知します。それ以外のツールはネットワークを使用しません。

• MEXICOAPI_BASE で API の接続先を変更できます。たとえば、独自のデプロイ先や wrangler dev のローカル API を指定できます。http:// の接続先は（0.2.0 以降）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 (desde 0.2.0)	32 の連邦構成単位と、そのコード（cve_ent）、名前、略称を取得します	いいえ
municipios_de_estado (desde 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 以降）。

各結果に含まれる内容

各結果にはスペイン語のテキストと、そのツールの outputSchema を満たす structuredContent が含まれます。

{
  "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 となり、Correos de México が日付を提供しなかった場合の codigo_postal でも null となります。その場合、descargado にカタログのダウンロード日が記載されます。
• fuente と fuentes：引用用の URL を含む公式資料です。fuente は fuentes の最初の項目です。
• origen：API（公開 API または MEXICOAPI_BASE）が応答した場合は api、mexicoapi パッケージのデータとルールから取得した場合は paquete、codigo_postal の場合は cache_local です。
• advertencias：API のエラーやカレンダーが不完全な可能性など、質問者に伝える必要のある情報です。
• avisos（0.2.0 以降）：同じ警告を同じ順序で格納し、それぞれに安定したコード（{ "codigo": "lft-art-715", "texto": "…" }）を付けたものです。プログラムはテキストを読まずに判断できます。sumar_dias_habilesにはdatos.avisos も含まれます。コードは[API ガイド](https://github.com/Dagel4k/mexicoapi/blob/main/docs/api/README.md#avisos)に記載されています。結果のテキストには警告のみが含まれます。 ツールが受け取り、返す日付（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 と同じで、最終データから今日までの日数を数えます。そのため、1つの回答に両方の警告が表示されることがあります。クライアントはパッケージの最新 FIX に同じ警告（AVISO_SIN_API）を表示し、0.2.0以降は1つの回答につき1回だけ表示されます。カレンダーと定数にはこの警告は不要です。パッケージが対応する範囲外の場合、以前の値ではなくエラーを返します。

ツールのエラー（無効な引数、存在しないデータ、対象期間をカバーしていないカレンダー、想定と異なる形式の 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）

郵便番号カタログは Correos de México のものであり、再配布できないため、このパッケージにも mexicoapi にも含まれていません。codigo_postal を使うには、カタログを一度お使いの端末にダウンロードしてください。

npx mexicoapi sepomex sync

このコマンドは Correos de México の利用に関する注意事項を表示し、カタログをローカルキャッシュに保存します（Windows では %LOCALAPPDATA%\mexicoapi\sepomex、その他の環境では $XDG_CACHE_HOME/mexicoapi/sepomex または ~/.cache/mexicoapi/sepomex）。サーバーはこのキャッシュのみを読み取ります。カタログがない場合、codigo_postal はエラーとダウンロード用のコマンドを返します。各結果には利用に関する注意事項が含まれます。また、これらのデータの利用には Correos de México の規約が適用されます。詳細は mexicoapi の README をご覧ください。

プライバシー

• テレメトリーはありません。
• サーバーが CLABE、RFC、CURP、NSS を API に送信することはありません。API を照会する場合も含め、これらはお使いの端末上で検証されます。
• これはサーバーに限った話です。アシスタントのホスト（アシスタントを実行するアプリケーション）は、会話のほかの内容と同様に、各ツールの引数と結果をモデルプロバイダーに送信します。端末の外に出してはいけないデータは、アシスタントに渡さないでください。
• サーバーが通信するのは、メキシコの公開 API、または MEXICOAPI_BASE で指定されたアドレスのみです。対象となるのは、有効期限のあるデータを扱うツールに限られます。MEXICOAPI_SIN_RED=1 を設定すると、ネットワークは使用されません。
• ログは stderr に出力され、ツールの引数や MEXICOAPI_BASE のアドレスが含まれることはありません。

プロトコル

• stdio トランスポート：1 行につき JSON-RPC メッセージ 1 件です。
• MCP のバージョン：2025-11-25、2025-06-18、2025-03-26、2024-11-05。別のバージョンを要求するクライアントには、2025-11-25 で応答します。
• 機能：tools のみで、listChanged はありません。
• ツールの一覧表示、呼び出し、および各結果の outputSchema に対する検証を行う、MCP 公式 TypeScript クライアントでテスト済みです。

ライセンス

コードは MIT です。データはこのプロジェクトのものではありません。公開元の機関（INEGI、Banxico、DOF、CNBV、SAT、CONASAMI）の規約が適用され、各結果に出典が記載されます。詳細は DATA_LICENSE.md をご覧ください。