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 (설정 → 개발자 → 설정 편집)을 수정하고 다음을 붙여넣으세요:

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

Claude Desktop을 재시작하세요. OS별 자세한 내용은 QUICKSTART.md를 참조하세요.

Cowork

동일한 JSON을 Cowork의 MCP 편집기에 붙여넣거나 리포지토리의 .mcp.json을 가리키세요.

🎯 첫 번째 테스트 프롬프트

Claude에 복사하여 붙여넣으세요:

2025년 Cuauhtémoc 자치구에서 가장 빈번하게 발생한 범죄 유형 10가지를 나열해 줘. 그 후 막대 이모지를 사용한 마크다운 표로 만들어 줘.

Claude가 자동으로 crime_hotspots를 선택하여 실제 데이터로 답변합니다. 더 많은 프롬프트는 **PROMPTS.md**에서 확인하세요.

📊 커버리지

마이그레이션 후 참고: 2026년 4월, 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는 푸시할 때마다 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를 사용하여 실제 스키마를 노출합니다.

• 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. 적절한 TTL과 함께 cache.cached(...)로 감쌉니다.

3. @mcp.tool()과 명확한 docstring(Claude가 읽음)을 사용하여 server.py에 노출합니다.

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

이슈와 PR은 언제나 환영합니다. .github/workflows/ci.yml 워크플로우는 Python 3.10 / 3.11 / 3.12에서 모든 것이 컴파일되는지 확인합니다.

📄 라이선스

MIT · Impact Lab CDMX 01 (2026년 4월)에서 rohan.mx · csar.dev 제작.

확장

새로운 소스를 추가하려면:

1. src/cdmx_mcp/adapters/<fuente>.py를 생성하고 딕셔너리를 반환하는 함수를 작성합니다.

2. TTL을 위해 cache.cached(...)로 감쌉니다.

3. @mcp.tool()을 사용하여 server.py에 노출합니다.

라이선스

MIT.