cdmx-mcp

Model Context Protocol para los datos abiertos de la Ciudad de México. Dale a Claude acceso directo a crimen, 911, calidad del aire, ECOBICI y DENUE — sin escribir una sola línea de código de ingesta.

"¿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

📋 Prerrequisitos

Necesitás Python 3.10+ y uv (gestor de paquetes moderno para Python — reemplaza a pip + venv + pyenv en un solo binario).

Instalar uv

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

O con Homebrew (macOS):

brew install uv

En PowerShell:

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

O con winget:

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

O con Scoop:

scoop install uv

Verificá que quedó instalado:

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

Instalar Python (si no lo tenés)

uv puede descargar e instalar Python por vos — no hace falta que lo instales manualmente:

uv python install 3.12

Igual, si preferís instalarlo a mano:

• macOS: brew install python@3.12 o desde https://www.python.org/downloads/

• Windows: winget install Python.Python.3.12 o desde la Microsoft Store

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

• Linux (Arch): sudo pacman -S python

Verificá:

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

💡 Con uv no necesitás activar venvs ni pelear con versiones — uv sync lee pyproject.toml + uv.lock y arma todo solo.

⚡ Quickstart — 30 segundos

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"

Ya está instalado. Ahora conectalo a tu cliente preferido:

Claude Code

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

O simplemente abrí este directorio con claude y detectará el .mcp.json automáticamente.

Claude Desktop

Editá claude_desktop_config.json (Settings → Developer → Edit Config) y pegá:

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

Reiniciá Claude Desktop. Detalle completo por SO → QUICKSTART.md.

Cowork

Pegá el mismo JSON en el editor de MCPs de Cowork, o apuntá al .mcp.json del repo.

🎯 Primer prompt de prueba

Copiá y pegá en Claude:

Lista los 10 tipos de delito más frecuentes en la alcaldía Cuauhtémoc durante 2025. Después hacé una tabla markdown con emojis de barra.

Claude elige crime_hotspots automáticamente y te contesta con datos reales. Más prompts en PROMPTS.md.

📊 Qué cubre

Nota post-migración: en abril 2026 el portal CDMX migró de OpenDataSoft a CKAN 2.10. Las consultas ahora pasan por /api/3/action/datastore_search_sql (PostgreSQL real). Los slugs de dataset se conservaron.

🛠 Tools expuestas (9 total)

Genéricas — funcionan con cualquier dataset del portal:

Recetas — atajos para el top 5:

Más cache_stats() y 2 recursos (cdmx://guide/fgj, cdmx://guide/top5).

Shortcuts soportados como dataset_id: fgj · 911 · ids · aire.

🧪 Verificar que funciona

# 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

El CI corre el smoke test en Python 3.10, 3.11 y 3.12 en cada push.

🔐 Token opcional para DENUE

denue_near requiere un token gratuito de INEGI:

1. Registrate en https://www.inegi.org.mx/servicios/api_denue.html (toma 2 min)

2. Exportalo antes de iniciar Claude Desktop/Code:

export INEGI_TOKEN=tu_token

O agregalo al env de tu config JSON — ver config/claude_desktop_config.example.json.

🏗 Arquitectura

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

• CKAN cubre 4 de las 5 fuentes (FGJ, 911, aire, IDS) con la misma API (/api/3/action/*).

• describe_dataset usa package_show + datastore_search para exponer el schema real.

• query_records y aggregate delegan en datastore_search_sql (PostgreSQL real: identificadores con ", literales con ').

• ECOBICI se consume por GBFS (feed estándar; también sobre-escribible vía ECOBICI_GBFS_URL).

• Cache en memoria con TTL por tool: 15 s para tiempo real, 10 min para queries, 1 h para catálogo.

• Sin tokens excepto DENUE (opcional).

📚 Aprende más

• PROMPTS.md — biblioteca de prompts listos para copiar/pegar agrupados por dominio (crimen, movilidad, aire, negocios, combos).

• QUICKSTART.md — instalación paso a paso por sistema operativo + troubleshooting.

• examples/ — demos específicas por canal:

  • demo-cowork.md · prompts para Cowork (stakeholders no técnicos).

  • demo-claude-desktop.md · flujo guiado en chat.

  • demo-claude-code.md · ejercicios avanzados en terminal con pandas/matplotlib.

🤝 Contribuir

El servidor está diseñado para extenderse fácilmente.

Para añadir una nueva fuente:

1. Crear src/cdmx_mcp/adapters/<fuente>.py con funciones que devuelvan dicts con la forma {"results": [...], "total_count": N}.

2. Envolverlas con cache.cached(...) con un TTL apropiado.

3. Exponerlas en server.py con @mcp.tool() y una docstring clara (Claude la lee).

4. Agregar el nombre al set expected en tests/smoke_test.py.

Correr CI local:

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

Issues y PRs son bienvenidos. El workflow de .github/workflows/ci.yml valida que todo compile en Python 3.10 / 3.11 / 3.12.

📄 Licencia

MIT · built at Impact Lab CDMX 01 (abril 2026) por rohan.mx · csar.dev.

Extender

Para añadir una fuente nueva:

1. Crear src/cdmx_mcp/adapters/<fuente>.py con funciones que devuelvan dicts.

2. Envolver con cache.cached(...) para TTL.

3. Exponer en server.py con @mcp.tool().

Licencia

MIT.