cdmx-mcp

Model Context Protocol für die offenen Daten von Mexiko-Stadt. Gib Claude direkten Zugriff auf Kriminalität, 911, Luftqualität, ECOBICI und DENUE — ohne eine einzige Zeile Aufnahmecode schreiben zu müssen.

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

📋 Voraussetzungen

Du benötigst Python 3.10+ und uv (moderner Paketmanager für Python — ersetzt pip + venv + pyenv durch ein einziges Binärprogramm).

uv installieren

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

Oder mit Homebrew (macOS):

brew install uv

In PowerShell:

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

Oder mit winget:

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

Oder mit Scoop:

scoop install uv

Überprüfe, ob die Installation erfolgreich war:

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

Python installieren (falls nicht vorhanden)

uv kann Python für dich herunterladen und installieren — du musst es nicht manuell installieren:

uv python install 3.12

Falls du es dennoch manuell installieren möchtest:

• macOS: brew install python@3.12 oder über https://www.python.org/downloads/

• Windows: winget install Python.Python.3.12 oder über den Microsoft Store

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

• Linux (Arch): sudo pacman -S python

Überprüfen:

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

💡 Mit uv musst du keine venvs aktivieren oder dich mit Versionen herumschlagen — uv sync liest pyproject.toml + uv.lock und richtet alles automatisch ein.

Related MCP server: MobusMCP

⚡ Quickstart — 30 Sekunden

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"

Es ist bereits installiert. Verbinde es nun mit deinem bevorzugten Client:

Claude Code

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

Oder öffne einfach dieses Verzeichnis mit claude, und es erkennt die .mcp.json automatisch.

Claude Desktop

Bearbeite claude_desktop_config.json (Einstellungen → Entwickler → Konfiguration bearbeiten) und füge Folgendes ein:

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

Starte Claude Desktop neu. Vollständige Details nach Betriebssystem → QUICKSTART.md.

Cowork

Füge dasselbe JSON in den MCP-Editor von Cowork ein oder verweise auf die .mcp.json des Repos.

🎯 Erster Test-Prompt

Kopiere dies und füge es in Claude ein:

Liste die 10 häufigsten Deliktarten im Bezirk Cuauhtémoc im Jahr 2025 auf. Erstelle danach eine Markdown-Tabelle mit Balken-Emojis.

Claude wählt automatisch crime_hotspots aus und antwortet mit echten Daten. Weitere Prompts unter PROMPTS.md.

📊 Was wird abgedeckt

Hinweis nach der Migration: Im April 2026 migrierte das CDMX-Portal von OpenDataSoft auf CKAN 2.10. Abfragen laufen nun über /api/3/action/datastore_search_sql (echtes PostgreSQL). Die Dataset-Slugs wurden beibehalten.

🛠 Verfügbare Tools (insgesamt 9)

Generisch — funktionieren mit jedem Dataset des Portals:

Rezepte — Abkürzungen für die Top 5:

Zusätzlich cache_stats() und 2 Ressourcen (cdmx://guide/fgj, cdmx://guide/top5).

Unterstützte Shortcuts als dataset_id: fgj · 911 · ids · aire.

🧪 Überprüfung der Funktionalität

# 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

Die CI führt bei jedem Push einen Smoke-Test unter Python 3.10, 3.11 und 3.12 durch.

🔐 Optionales Token für DENUE

denue_near erfordert ein kostenloses Token von INEGI:

1. Registriere dich unter https://www.inegi.org.mx/servicios/api_denue.html (dauert 2 Min.)

2. Exportiere es, bevor du Claude Desktop/Code startest:

export INEGI_TOKEN=tu_token

Oder füge es zum env deiner JSON-Konfiguration hinzu — siehe config/claude_desktop_config.example.json.

🏗 Architektur

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

• CKAN deckt 4 der 5 Quellen (FGJ, 911, Luft, IDS) mit derselben API ab (/api/3/action/*).

• describe_dataset verwendet package_show + datastore_search, um das echte Schema offenzulegen.

• query_records und aggregate delegieren an datastore_search_sql (echtes PostgreSQL: Bezeichner mit ", Literale mit ').

• ECOBICI wird über GBFS konsumiert (Standard-Feed; auch überschreibbar via ECOBICI_GBFS_URL).

• Cache im Arbeitsspeicher mit TTL pro Tool: 15 s für Echtzeit, 10 min für Abfragen, 1 h für Katalog.

• Keine Token erforderlich, außer für DENUE (optional).

📚 Mehr erfahren

• PROMPTS.md — Bibliothek mit fertigen Prompts zum Kopieren/Einfügen, gruppiert nach Themen (Kriminalität, Mobilität, Luft, Unternehmen, Kombinationen).

• QUICKSTART.md — Schritt-für-Schritt-Installation nach Betriebssystem + Fehlerbehebung.

• examples/ — Spezifische Demos nach Kanal:

  • demo-cowork.md · Prompts für Cowork (nicht-technische Stakeholder).

  • demo-claude-desktop.md · Geführter Chat-Ablauf.

  • demo-claude-code.md · Fortgeschrittene Übungen im Terminal mit pandas/matplotlib.

🤝 Mitwirken

Der Server ist so konzipiert, dass er leicht erweitert werden kann.

Um eine neue Quelle hinzuzufügen:

1. Erstelle src/cdmx_mcp/adapters/<quelle>.py mit Funktionen, die Dicts in der Form {"results": [...], "total_count": N} zurückgeben.

2. Umhülle sie mit cache.cached(...) mit einem geeigneten TTL.

3. Stelle sie in server.py mit @mcp.tool() und einem klaren Docstring bereit (Claude liest diesen).

4. Füge den Namen zum Set expected in tests/smoke_test.py hinzu.

Lokale CI ausführen:

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

Issues und PRs sind willkommen. Der Workflow in .github/workflows/ci.yml validiert, dass alles unter Python 3.10 / 3.11 / 3.12 kompiliert.

📄 Lizenz

MIT · erstellt im Impact Lab CDMX 01 (April 2026) von rohan.mx · csar.dev.

Erweitern

Um eine neue Quelle hinzuzufügen:

1. Erstelle src/cdmx_mcp/adapters/<quelle>.py mit Funktionen, die Dicts zurückgeben.

2. Umhülle sie mit cache.cached(...) für TTL.

3. Stelle sie in server.py mit @mcp.tool() bereit.

Lizenz

MIT.