turkiye-energy-mcp

Türkiye elektrik sistemine ilişkin doğrulanmış resmî kamu verilerini Model Context Protocol (MCP) üzerinden sunan bağımsız Python sunucusu.

Kapsam yalnızca:

• TEİAŞ

• EÜAŞ konusu için TEİAŞ'ın yayımladığı resmî tablolar

EPİAŞ bilinçli olarak kapsam dışıdır. EÜAŞ konusu TEİAŞ kaynağından geldiğinde yanıt "source": "TEİAŞ", "subject": "EÜAŞ" taşır. Kaynağı doğrulanamayan tool yayınlanmaz.

Veri yaklaşımı

Sunucu, TEİAŞ web sitesinin kendi istemcisinin kullandığı resmî JSON galeri kataloğunu okur ve katalogda listelenen XLS/XLSX dosyalarını indirir:

1. https://www.teias.gov.tr/api/gallery

2. https://webim.teias.gov.tr/file/{media_slug}?download

HTML scraping production veri yolunda kullanılmaz. EÜAŞ web sitesi keşif sırasında aralıklı TLS reset/HTTP 500 ürettiğinden EÜAŞ HTML sayfaları production kaynağına alınmamıştır. Ayrıntılı keşif ve uygulanamayan veri setleri: docs/data-discovery.md.

Related MCP server: strompreis-mcp

Mimari

turkiye_energy_mcp/
├── server.py              # MCP tool kayıtları ve transport
├── service.py             # veri setleri ve kaynaklar arası hesaplamalar
├── clients/teias.py       # resmî JSON katalog/dosya istemcisi
├── parsers/               # Türkçe sayı/tarih ve XLS/XLSX ayrıştırıcıları
├── http_client.py         # ortak async connection pool, retry/backoff
├── cache.py               # eşzamanlı istek birleştiren TTL cache
├── models.py              # ortak response standardı
├── exceptions.py          # yapılandırılmış hata kodları
└── config.py              # environment ayarları

• Python 3.11+

• Resmî MCP Python SDK 2.x (MCPServer; FastMCP'nin güncel adı)

• httpx.AsyncClient

• Pydantic Settings

• pandas/openpyxl/xlrd

• async I/O, exponential backoff ve connection pooling

• Streamable HTTP ve stdio

Kurulum

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

Geliştirme bağımlılıkları:

pip install -e '.[dev]'
pytest

Çalıştırma

Streamable HTTP:

MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 turkiye-energy-mcp

• MCP endpoint: http://localhost:8000/mcp

• Health endpoint: http://localhost:8000/health

stdio:

MCP_TRANSPORT=stdio turkiye-energy-mcp

Environment variables

Tüm örnekler .env.example içindedir.

Railway deploy

Depo Dockerfile ve railway.toml içerir.

railway up

Railway'de MCP_TRANSPORT=streamable-http ve HOST=0.0.0.0 kullanın. PORT Railway tarafından atanır. Deploy sonrası endpoint:

https://<railway-domain>/mcp

MCP tool'ları

Toplam 16 production tool vardır.

Tarih biçimi YYYY-MM-DD, timezone Europe/Istanbul'dur. Yıllık tool'lar tam yıl alır. Güç MW, enerji GWh, trafo kapasitesi MVA, hat uzunluğu km olarak açık alan adlarıyla döner.

Response standardı

{
  "source": "TEİAŞ",
  "subject": "EÜAŞ",
  "dataset": "installed_capacity",
  "start_date": "2020",
  "end_date": "2024",
  "unit": "MW",
  "data": [],
  "metadata": {
    "retrieved_at": "2026-08-11T13:00:00+03:00",
    "source_url": "https://webim.teias.gov.tr/file/...",
    "source_format": "xls",
    "frequency": "annual",
    "notes": null,
    "original_unit": "MW"
  }
}

Hatalar traceback yerine:

{
  "error": true,
  "code": "DATA_NOT_AVAILABLE",
  "message": "Belirtilen dönem için veri bulunamadı.",
  "source": "TEİAŞ"
}

Kodlar: DATA_NOT_AVAILABLE, SOURCE_UNAVAILABLE, PARSING_ERROR, INVALID_PARAMETER, RATE_LIMITED, AUTH_REQUIRED.

Cursor config

Remote Streamable HTTP (~/.cursor/mcp.json):

{
  "mcpServers": {
    "turkiye-energy": {
      "url": "https://<railway-domain>/mcp"
    }
  }
}

Local stdio:

{
  "mcpServers": {
    "turkiye-energy": {
      "command": "/absolute/path/turkiye-energy-mcp/.venv/bin/turkiye-energy-mcp",
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Claude config

Claude Code remote HTTP:

claude mcp add --transport http turkiye-energy https://<railway-domain>/mcp

Claude Desktop local stdio config:

{
  "mcpServers": {
    "turkiye-energy": {
      "command": "/absolute/path/turkiye-energy-mcp/.venv/bin/turkiye-energy-mcp",
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Örnek promptlar

• “2024 yılında Türkiye'nin toplam elektrik üretimi ne kadardı?”

• “2024 sonunda Türkiye'nin kaynak bazında kurulu gücünü getir.”

• “2006-2024 arasında Türkiye'nin rüzgâr kurulu gücü nasıl değişti?”

• “EÜAŞ hidroelektrik santrallerini kurulu güçlerine göre sırala.”

• “EÜAŞ'ın Türkiye toplam elektrik üretimindeki payını 2014-2024 için göster.”

• “Türkiye'nin Bulgaristan ve Yunanistan ile elektrik ithalat/ihracatını karşılaştır.”

• “Son beş kesinleşmiş yıldaki puant talep büyümesini hesapla.”

Resmî kaynaklar ve tarihsel derinlik

Test ve smoke test

Ana testler internet kullanmaz:

pytest

Gerçek resmî endpoint ve 16 production veri yolu:

python scripts/smoke_test.py

Smoke test internet gerektirir ve başarısız tool varsa non-zero exit code döndürür.

Bilinen sınırlamalar

• TEİAŞ JSON galeri endpointi resmî sitenin kullandığı fakat belgelenmemiş bir web uygulaması sözleşmesidir; şema/slug değişikliği riski vardır.

• Kesinleşmiş yıllık seri şu anda 2024'te biter. Cari aylık değerler geçici olabilir.

• Saatlik tüketim ve günlük yük eğrisi için kararlı, doğrulanmış makine endpointi bulunmadığından tool yoktur.

• Ülke bazlı dış ticaret 2012-2024 yıllık çalışma kitabıyla sınırlıdır.

• EÜAŞ'ın kendi sitesi kararsız olduğundan veri yolu değildir. EÜAŞ tool'ları TEİAŞ'ın EÜAŞ konulu resmî tablolarını kullanır.

• EÜAŞ santral çalışma kitabındaki güvenilir olmayan ünite/devreye giriş hücreleri yayımlanmaz.

• EÜAŞ operasyonel performans, duruş, bakım ve bütünlüklü yatırım serileri için doğrulanmış açık veri bulunmadığından tool yayınlanmaz.