cdmx-mcp

Model Context Protocol для открытых данных Мехико. Дайте 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. Полные детали по ОС → QUICKSTART.md.

Cowork

Вставьте тот же JSON в редактор MCP в Cowork или укажите путь к .mcp.json в репозитории.

🎯 Первый тестовый промпт

Скопируйте и вставьте в Claude:

Перечисли 10 наиболее частых видов преступлений в районе Куаутемок за 2025 год. Затем создай таблицу в формате markdown с эмодзи-гистограммами.

Claude автоматически выберет crime_hotspots и ответит реальными данными. Больше промптов в PROMPTS.md.

📊 Что охватывает

Примечание после миграции: в апреле 2026 года портал CDMX перешел с OpenDataSoft на CKAN 2.10. Запросы теперь проходят через /api/3/action/datastore_search_sql (настоящий PostgreSQL). Слаги наборов данных были сохранены.

🛠 Доступные инструменты (всего 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 запускает smoke-тесты на 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

Или добавьте его в env вашего конфигурационного JSON — см. 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 покрывает 4 из 5 источников (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 — пошаговая установка по операционным системам + устранение неполадок.

• 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. Оберните их в cache.cached(...) с подходящим TTL.

3. Опубликуйте их в server.py с помощью @mcp.tool() и четкой docstring (Claude её читает).

4. Добавьте имя в набор expected в tests/smoke_test.py.

Запуск CI локально:

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

Issues и PR приветствуются. Воркфлоу .github/workflows/ci.yml проверяет, что всё компилируется на Python 3.10 / 3.11 / 3.12.

📄 Лицензия

MIT · создано в Impact Lab CDMX 01 (апрель 2026) авторами rohan.mx · csar.dev.

Расширение

Чтобы добавить новый источник:

1. Создайте src/cdmx_mcp/adapters/<fuente>.py с функциями, возвращающими словари.

2. Оберните в cache.cached(...) для TTL.

3. Опубликуйте в server.py с помощью @mcp.tool().

Лицензия

MIT.