cdmx-mcp

Model Context Protocol for Mexico City's open data. Claudeに犯罪、911通報、大気質、ECOBICI、DENUEへの直接アクセス権を与えましょう。データ取り込みコードを一行も書く必要はありません。

"¿Cuáles son las 10 colonias con más delitos en Cuauhtémoc en 2025?"
  ↓  Claude llama crime_hotspots(year=2025, alcaldia="CUAUHTEMOC", top_n=10)
  ↓  cdmx-mcp traduce a SQL contra CKAN
  ↓  Claude te contesta con la tabla + análisis, en segundos

📋 前提条件

Python 3.10+ と uv (Python用のモダンなパッケージマネージャー。pip + venv + pyenvを単一のバイナリに置き換えます) が必要です。

uv のインストール

curl -LsSf https://astral.sh/uv/install.sh | sh

またはHomebrew (macOS) を使用:

brew install uv

PowerShell で実行:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

または winget を使用:

winget install --id=astral-sh.uv -e

または Scoop を使用:

scoop install uv

インストールされたことを確認します:

uv --version   # → uv 0.5.x o similar

Pythonのインストール (未インストールの場合)

uv がPythonをダウンロードしてインストールできるため、手動でインストールする必要はありません:

uv python install 3.12

それでも手動でインストールしたい場合は、以下を参照してください:

• macOS: brew install python@3.12 または https://www.python.org/downloads/ から

• Windows: winget install Python.Python.3.12 または Microsoft Store から

• Linux (Ubuntu/Debian): sudo apt install python3.12 python3.12-venv

• Linux (Arch): sudo pacman -S python

確認:

python3 --version   # → Python 3.10.x o superior

💡 uv を使えば、venvを有効にしたりバージョン管理に悩む必要はありません。uv sync が pyproject.toml と uv.lock を読み込んで自動的にすべてを構築します。

Related MCP server: MobusMCP

⚡ クイックスタート — 30秒

git clone https://github.com/devcsar/cdmx-mcp.git
cd cdmx-mcp
uv sync                                   # instala Python + dependencias
uv run python tests/smoke_test.py         # verifica: debe decir "smoke: OK"

インストールは完了です。お好みのクライアントに接続しましょう:

Claude Code

claude mcp add cdmx -- uv --directory "$(pwd)" run cdmx-mcp
claude                                    # dentro de la sesión: /mcp

または、このディレクトリを claude で開くだけで、.mcp.json が自動的に検出されます。

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config) を編集し、以下を貼り付けます:

{
  "mcpServers": {
    "cdmx": {
      "command": "uv",
      "args": ["--directory", "/ruta/absoluta/a/cdmx-mcp", "run", "cdmx-mcp"]
    }
  }
}

Claude Desktopを再起動します。OSごとの詳細は QUICKSTART.md を参照してください。

Cowork

CoworkのMCPエディタに同じJSONを貼り付けるか、リポジトリの .mcp.json を指定してください。

🎯 最初のテストプロンプト

Claudeにコピー＆ペーストしてください:

2025年のクアウテモック区で最も頻繁に発生した犯罪の種類を10個リストアップしてください。その後、棒グラフの絵文字を使ったマークダウンテーブルを作成してください。

Claudeは自動的に crime_hotspots を選択し、実際のデータで回答します。その他のプロンプトは PROMPTS.md にあります。

📊 カバー範囲

移行後の注意: 2026年4月、CDMXポータルはOpenDataSoftから CKAN 2.10 に移行しました。クエリは現在 /api/3/action/datastore_search_sql (実際のPostgreSQL) を経由します。データセットの slug は維持されています。

🛠 公開ツール (計9個)

汎用 — ポータルのあらゆるデータセットで動作します:

レシピ — 上位5つのショートカット:

さらに cache_stats() と2つのリソース (cdmx://guide/fgj, cdmx://guide/top5) があります。

dataset_id としてサポートされているショートカット: fgj · 911 · ids · aire。

🧪 動作確認

# Test offline (no golpea el portal)
uv run python tests/smoke_test.py
# → smoke: OK

# Test live (opcional — consulta real a datos.cdmx.gob.mx)
CDMX_MCP_LIVE=1 uv run python tests/live_test.py
# → live: OK

CIは、プッシュごとに Python 3.10, 3.11, 3.12 でスモークテストを実行します。

🔐 DENUE用オプショントークン

denue_near にはINEGIの無料トークンが必要です:

1. https://www.inegi.org.mx/servicios/api_denue.html で登録 (2分で完了)

2. Claude Desktop/Codeを起動する前にエクスポートします:

export INEGI_TOKEN=tu_token

または、設定JSONの env に追加してください — config/claude_desktop_config.example.json を参照。

🏗 アーキテクチャ

Claude (Desktop / Cowork / Code)
          │  stdio · JSON-RPC
          ▼
   cdmx_mcp.server (FastMCP)
          │
   ┌──────┴──────┬───────────┬──────────┐
   ▼             ▼           ▼          ▼
   ckan        gbfs        denue      cache
(datos.cdmx) (ECOBICI)   (INEGI)   (TTL + LRU)

• CKAN は5つのソースのうち4つ (FGJ, 911, 大気質, IDS) を同じAPI (/api/3/action/*) でカバーします。

• describe_dataset は package_show + datastore_search を使用して実際のスキーマを公開します。

• query_records と aggregate は datastore_search_sql (実際のPostgreSQL: 識別子は "、リテラルは ' で囲む) に委譲します。

• ECOBICI はGBFS (標準フィード; ECOBICI_GBFS_URL で上書き可能) で消費されます。

• キャッシュ はツールごとのTTLでメモリ内に保持: リアルタイムは15秒、クエリは10分、カタログは1時間。

• DENUE (オプション) を除き、トークンは不要です。

📚 詳細はこちら

• PROMPTS.md — ドメイン別 (犯罪、モビリティ、大気質、ビジネス、コンボ) に整理された、コピー＆ペースト可能なプロンプトライブラリ。

• QUICKSTART.md — OSごとのステップバイステップインストール + トラブルシューティング。

• examples/ — チャネル別のデモ:

  • demo-cowork.md · Cowork用プロンプト (非技術系ステークホルダー向け)。

  • demo-claude-desktop.md · チャットでのガイド付きフロー。

  • demo-claude-code.md · pandas/matplotlibを使用したターミナルでの高度な演習。

🤝 貢献

サーバーは簡単に拡張できるように設計されています。

新しいソースを追加するには:

1. src/cdmx_mcp/adapters/<fuente>.py を作成し、{"results": [...], "total_count": N} という形式の辞書を返す関数を実装します。

2. 適切なTTLで cache.cached(...) を使用してラップします。

3. server.py で @mcp.tool() と明確なdocstring (Claudeが読み取ります) を付けて公開します。

4. tests/smoke_test.py の expected セットに名前を追加します。

ローカルCIの実行:

uv run python tests/smoke_test.py
CDMX_MCP_LIVE=1 uv run python tests/live_test.py   # requiere internet

IssueやPRを歓迎します。.github/workflows/ci.yml ワークフローは、Python 3.10 / 3.11 / 3.12 でのコンパイルを検証します。

📄 ライセンス

MIT · Impact Lab CDMX 01 (2026年4月) にて rohan.mx · csar.dev により構築。

拡張

新しいソースを追加するには:

1. src/cdmx_mcp/adapters/<fuente>.py を作成し、辞書を返す関数を実装します。

2. TTLのために cache.cached(...) でラップします。

3. server.py で @mcp.tool() を使用して公開します。

ライセンス

MIT。