cdmx-mcp

Model Context Protocol for Mexico City's open data. Give Claude direct access to crime, 911, air quality, ECOBICI, and DENUE — without writing a single line of ingestion code.

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

📋 Prerequisites

You need Python 3.10+ and uv (a modern Python package manager — replaces pip + venv + pyenv in a single binary).

Install uv

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

Or with Homebrew (macOS):

brew install uv

In PowerShell:

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

Or with winget:

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

Or with Scoop:

scoop install uv

Verify that it is installed:

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

Install Python (if you don't have it)

uv can download and install Python for you — you don't need to install it manually:

uv python install 3.12

However, if you prefer to install it manually:

• macOS: brew install python@3.12 or from https://www.python.org/downloads/

• Windows: winget install Python.Python.3.12 or from the Microsoft Store

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

• Linux (Arch): sudo pacman -S python

Verify:

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

💡 With uv you don't need to activate venvs or fight with versions — uv sync reads pyproject.toml + uv.lock and sets everything up on its own.

Related MCP server: MobusMCP

⚡ Quickstart — 30 seconds

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"

It is already installed. Now connect it to your preferred client:

Claude Code

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

Or simply open this directory with claude and it will automatically detect the .mcp.json.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config) and paste:

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

Restart Claude Desktop. Full details by OS → QUICKSTART.md.

Cowork

Paste the same JSON into the Cowork MCP editor, or point to the .mcp.json in the repo.

🎯 First test prompt

Copy and paste into Claude:

List the 10 most frequent types of crime in the Cuauhtémoc borough during 2025. Then create a markdown table with bar emojis.

Claude automatically chooses crime_hotspots and answers with real data. More prompts in PROMPTS.md.

📊 What it covers

Post-migration note: in April 2026 the CDMX portal migrated from OpenDataSoft to CKAN 2.10. Queries now go through /api/3/action/datastore_search_sql (real PostgreSQL). Dataset slugs were preserved.

🛠 Exposed Tools (9 total)

Generic — work with any dataset on the portal:

Recipes — shortcuts for the top 5:

Plus cache_stats() and 2 resources (cdmx://guide/fgj, cdmx://guide/top5).

Shortcuts supported as dataset_id: fgj · 911 · ids · aire.

🧪 Verify it works

# 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

The CI runs the smoke test on Python 3.10, 3.11, and 3.12 on every push.

🔐 Optional token for DENUE

denue_near requires a free INEGI token:

1. Register at https://www.inegi.org.mx/servicios/api_denue.html (takes 2 min)

2. Export it before starting Claude Desktop/Code:

export INEGI_TOKEN=tu_token

Or add it to the env of your JSON config — see config/claude_desktop_config.example.json.

🏗 Architecture

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

• CKAN covers 4 of the 5 sources (FGJ, 911, air, IDS) with the same API (/api/3/action/*).

• describe_dataset uses package_show + datastore_search to expose the real schema.

• query_records and aggregate delegate to datastore_search_sql (real PostgreSQL: identifiers with ", literals with ').

• ECOBICI is consumed via GBFS (standard feed; also overridable via ECOBICI_GBFS_URL).

• Cache in memory with TTL per tool: 15 s for real-time, 10 min for queries, 1 h for catalog.

• No tokens except DENUE (optional).

📚 Learn more

• PROMPTS.md — library of ready-to-copy/paste prompts grouped by domain (crime, mobility, air, business, combos).

• QUICKSTART.md — step-by-step installation by operating system + troubleshooting.

• examples/ — specific demos by channel:

  • demo-cowork.md · prompts for Cowork (non-technical stakeholders).

  • demo-claude-desktop.md · guided chat flow.

  • demo-claude-code.md · advanced terminal exercises with pandas/matplotlib.

🤝 Contributing

The server is designed to be easily extended.

To add a new source:

1. Create src/cdmx_mcp/adapters/<source>.py with functions that return dicts in the form {"results": [...], "total_count": N}.

2. Wrap them with cache.cached(...) with an appropriate TTL.

3. Expose them in server.py with @mcp.tool() and a clear docstring (Claude reads it).

4. Add the name to the expected set in tests/smoke_test.py.

Run local CI:

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

Issues and PRs are welcome. The .github/workflows/ci.yml workflow validates that everything compiles in Python 3.10 / 3.11 / 3.12.

📄 License

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

Extend

To add a new source:

1. Create src/cdmx_mcp/adapters/<source>.py with functions that return dicts.

2. Wrap with cache.cached(...) for TTL.

3. Expose in server.py with @mcp.tool().

License

MIT.