İzmir Open Data MCP

İzmir Büyükşehir Belediyesi açık verisini (ESHOT, Metro, İZBAN, İZDENİZ, eczaneler) Claude gibi yapay zekâ asistanlarına MCP araçları olarak sunan sunucu. Yaşar Üniversitesi, Güz 2026 dönem projesi (Proje 09). Ekip: Sude Naz Çakır, Bahar Dokur.

"Bornova Metro durağına sıradaki otobüs ne zaman?"
"Buca'da nöbetçi eczane hangisi?"

Araçlar

Her araç aynı zarfı döndürür: veri + meta (kaynak, zaman, önbellek, notlar) + kaynak çökerse error (source_unavailable, timeout, not_found, invalid_input, bad_response). Araçlar hata durumunda istisna fırlatmaz, açıklamalı bir hata nesnesi döndürür; böylece Claude "kaynak şu an cevap vermiyor" diyebilir.

Varış süresi nasıl hesaplanıyor? ESHOT dakika vermiyor, sadece kalan durak sayısı ve otobüsün konumunu veriyor. Tahmin = (kalan durak × 1,5 dk + otobüsün durağa yol mesafesi ÷ 18 km/sa) / 2. Katsayılar .env içinden ayarlanabilir.

Durak adı nasıl bulunuyor? Önce veritabanındaki stops tablosuna bakılır. Tablo boşsa ya da veritabanı yoksa, addaki metro/İZBAN istasyonu, iskele ya da ilçe adının koordinatı bulunur ve o noktaya yakın duraklar arasından ada göre seçilir. Bornova Metro gibi aktarma merkezlerinde aynı adlı 10 perona birden bakılır.

Related MCP server: transport12 MCP Server

Kurulum

Gereken: Python 3.11+ ve uv.

git clone https://github.com/sudenazcakir/izmir-mcp.git
cd izmir-mcp
uv sync --extra dev
cp .env.example .env        # DATABASE_URL'yi doldur (isteğe bağlı)
uv run pytest               # çevrimdışı testler
uv run pytest -m live       # gerçek İzmir API'sine karşı duman testi

Veritabanı olmadan da iki araç çalışır; veritabanı durak adı aramasını hızlandırır ve 3. haftadaki API anahtarları ile kullanım kayıtları için gerekir.

Veritabanı (Supabase)

1. Supabase projesinde Connect > Direct (Connection string) > Session pooler adresini kopyala, şifreyi yerleştir, .env içine DATABASE_URL= olarak yaz. (Direct connection yalnız IPv6, Render'dan bağlanamaz.)

2. Şemayı kur: Supabase SQL Editor'e supabase/migrations/0001_init.sql dosyasını yapıştırıp çalıştır, ya da psql "$DATABASE_URL" -f supabase/migrations/0001_init.sql. Dosya tekrar çalıştırılabilir.

3. Statik verileri yükle:

uv run python jobs/ingest_static.py --dry-run   # önce yazmadan dene
uv run python jobs/ingest_static.py             # districts, stations, piers, pharmacies, stops, lines

Tablolar: districts (30 ilçe), stops, bus_lines, stations (metro + İZBAN), piers, pharmacies, api_keys, usage_logs. Tüm tablolarda RLS açık ve politika yok: Supabase'in herkese açık REST ucundan okunamazlar, sunucu doğrudan Postgres bağlantısıyla erişir.

MCP Inspector ile deneme

npx @modelcontextprotocol/inspector uv run izmir-mcp

Tarayıcıda açılan arayüzde Connect > Tools > List Tools, sonra find_pharmacies için district=Buca. Arayüzsüz:

npx @modelcontextprotocol/inspector --cli uv run izmir-mcp --method tools/call \
  --tool-name get_stop_arrivals --tool-arg "stop=Bornova Metro"

Claude Desktop'a bağlama (stdio)

Claude Desktop > Settings > Developer > Edit Config ile claude_desktop_config.json dosyasını aç ve şunu ekle (yolu kendi bilgisayarına göre değiştir):

macOS:

{
  "mcpServers": {
    "izmir": {
      "command": "/Users/KULLANICI/.local/bin/uv",
      "args": ["--directory", "/Users/KULLANICI/izmir-mcp", "run", "izmir-mcp"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "izmir": {
      "command": "C:\\Users\\KULLANICI\\.local\\bin\\uv.exe",
      "args": ["--directory", "C:\\Users\\KULLANICI\\izmir-mcp", "run", "izmir-mcp"]
    }
  }
}

uv'nin tam yolunu which uv (macOS) ya da where uv (Windows) ile bulabilirsin; Claude Desktop terminalin PATH'ini görmediği için tam yol gerekiyor. Kaydedip Claude Desktop'ı tamamen kapatıp yeniden aç. Sohbet kutusundaki araç simgesinde izmir görünmeli. Sorun olursa log: macOS ~/Library/Logs/Claude/mcp-server-izmir.log, Windows %APPDATA%\Claude\logs\mcp-server-izmir.log.

Uzak sunucu (3. hafta)

uv run izmir-mcp --http Streamable HTTP ile /mcp yolunda çalışır (PORT ortam değişkeni). Render'a Docker ile kurulum ve API anahtarı doğrulaması 3. haftada eklenecek.

Klasör yapısı

src/izmir_mcp/
  server.py            MCP sunucusu, araç tanımları
  tools.py             araçların iş mantığı
  models.py            ortak Pydantic modelleri (Arrival, Pharmacy, AirReading, Meta, SourceError…)
  http.py, cache.py    zaman aşımı + tekrar deneme, TTL önbellek + son iyi değer (2. haftada Redis)
  sources/             kaynak başına adaptör (eshot, pharmacy, transit_static)
  districts.py         30 ilçe ve merkez koordinatı
  ingest.py            gece yükleme işinin mantığı
  data/                API çökerse kullanılacak istasyon/iskele anlık görüntüsü
jobs/ingest_static.py  gece yükleme işi
supabase/migrations/   veritabanı şeması
docs/sources.md        denenmiş veri kaynakları ve uç noktalar
tests/                 çevrimdışı testler (+ `-m live` ile canlı testler)

Bilinen sınırlar

• Varış süreleri tahmindir, ESHOT'un resmî dakikası değildir.

• Nöbet bölgeleri (ör. BUCA 1, ŞİRİNYER) ilçe sınırıyla birebir örtüşmez; ilçe adıyla eşleşenler ve ilçe merkezine 5 km'den yakın olanlar birlikte gösterilir.

• ESHOT durak ve hat listesi acikveriwapi.izmir.bel.tr üzerinden geliyor; alan adları belgelerde net olmadığı için yükleyici birkaç olası yazımı dener. İlk gerçek çalıştırmada stops ve lines adımlarının sonucunu kontrol edin.

• pharmacies.district_id en yakın ilçe merkezine göre atanır (yaklaşık).

Lisans

MIT