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，你无需激活虚拟环境或处理版本冲突 — 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 粘贴到 Cowork 的 MCP 编辑器中，或指向仓库中的 .mcp.json。

🎯 第一个测试提示词

复制并粘贴到 Claude：

列出 2025 年 Cuauhtémoc 区最常见的 10 种犯罪类型。然后制作一个带有条形表情符号的 Markdown 表格。

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 通过相同的 API (/api/3/action/*) 覆盖了 5 个数据源中的 4 个（FGJ、911、空气、IDS）。

• describe_dataset 使用 package_show + datastore_search 来公开真实 Schema。

• query_records 和 aggregate 委托给 datastore_search_sql（真正的 PostgreSQL：标识符使用 "，字面量使用 '）。

• ECOBICI 通过 GBFS（标准 feed；也可通过 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. 使用适当的 TTL 用 cache.cached(...) 包装它们。

3. 在 server.py 中使用 @mcp.tool() 和清晰的文档字符串（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 · 由 rohan.mx 和 csar.dev 在 Impact Lab CDMX 01 (2026 年 4 月) 构建。

扩展

添加新数据源：

1. 创建 src/cdmx_mcp/adapters/<fuente>.py，函数返回字典。

2. 使用 cache.cached(...) 包装以设置 TTL。

3. 在 server.py 中使用 @mcp.tool() 公开。

许可证

MIT。