MEDAS MCP (Still in development!)

MCP server for TÜİK MEDAS (Turkish Statistical Institute indicators).

Features

• 92 topics — all TÜİK statistical categories
• 400+ indicators — cached instantly, live fallback available
• Dynamic discovery — 0 hardcoded widget IDs, adaptive to UI changes
• Cache-first — list_topics/get_indicators/download all <50ms from cache
• Binary XLS — xlwt CDFV2 Excel output (same format as MEDAS pivot.xls)
• Smart cascading — auto-selects mandatory breakdowns (COICOP, SITC, etc.)
• ZK Widget API — robust kırılım handling via zk.Widget.$().fire()

Install

pip install playwright xlwt httpx
playwright install chromium

Or with uv:

uv pip install -e .
playwright install chromium

Usage

As MCP server (stdio)

python server.py

Pi integration

Add to ~/.pi/config.json:

{
  "extensions": {
    "medas": {
      "command": "python",
      "args": ["/path/to/medas_mcp/server.py"],
      "cwd": "/path/to/medas_mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "medas": {
      "command": "python",
      "args": ["/path/to/medas_mcp/server.py"]
    }
  }
}

Tools

Tool	Description	Speed
list_topics(search?)	List 92 TÜİK topics	<50ms (cache)
get_indicators(topic_index)	Get indicators + cascading branches	<50ms (cache)
download(topic_index, indicators?, format?, save_path?, live?)	Download XLS/CSV report	<50ms cache / ~12s live

Example flow

1. list_topics("fiyat") → [{index:78, label:"Tüketici Fiyat Endeksi"}]
2. get_indicators(78) → {count:12, indicators:[...]}
3. download(78, format="xls") → /tmp/MEDAS_Tüketici_Fiyat_Endeksi_20260820.xls

Architecture

AI Agent  ⇄  MCP (stdio)  ⇄  server.py  ⇄  medas_client.py
                                            ├─ cache (data/*.json) → instant
                                            └─ Playwright (live=true) → ZK AU protocol

Cache vs Live

Mode	Source	Speed	Data
live=false (default)	data/*.json cache	<50ms	Indicator names + mock values
live=true	POST /medas/zkau → GET /pivot.xls	~12s	Real MEDAS pivot table

Files

medas_mcp/
├── server.py              # MCP server (3 tools)
├── medas_client.py        # Hybrid client (cache + live Playwright)
├── KNOWHOW.md             # ZK AU protocol traffic notes
├── AGENTS.md              # AI agent instructions
├── README.md              # This file
├── pyproject.toml         # Package metadata
├── .gitignore
└── data/
    ├── topic_mapping.json  # 92 topics with URLs
    ├── topic_gosterge.json # Indicators + cascading branches
    └── medas_unified.json  # Unified dataset

ZK AU Protocol

• POST /medas/zkau;jsessionid=XXX with dtid + batched cmd_n=onSelect/onClick
• Widget IDs change every session — discovered dynamically via DOM
• Cascading: zk.Widget.$('#selectId').fire('onSelect', {items:[itemId], reference:itemId})

License

MIT