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: mcp-entso-e

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

Yıllık/aylık kaynak seçimi sabit yıl veya sabit dosya adına bağlı değildir. Sunucu TEİAŞ galeri kataloğundan en yeni yayın tarihli ve en güncel dönemi kapsayan resmî dosyayı otomatik seçer.

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

Railway deploy

Depo Dockerfile ve railway.toml içerir.

railway up

Railway'de MCP_TRANSPORT=streamable-http, HOST=0.0.0.0 ve PUBLIC_BASE_URL=https://<railway-domain> kullanın. PORT Railway tarafından atanır. Deploy sonrası Claude/Cursor 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",
    "latest_available_period": "2024",
    "data_freshness": "current",
    "publication_date": "2026-01-15T12:06:51+00:00",
    "selected_source_name": "13-Yıllar İtibariyle ... (2006-2024).xls"
  }
}

data_freshness değerleri: current, provisional, historical, partial, unavailable. İstenen güncel dönem yoksa eski veri sessizce güncel gibi döndürülmez; latest_available_period ve data_freshness açıkça verilir veya hata detayında yer alır.

Hatalar traceback yerine:

{
  "error": true,
  "code": "DATA_NOT_AVAILABLE",
  "message": "Belirtilen dönem için veri bulunamadı.",
  "source": "TEİAŞ",
  "details": {
    "latest_available_period": "2024",
    "data_freshness": "unavailable",
    "requested_period": "2027"
  }
}

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 custom connector (claude.ai / Desktop Connect UI) için MCP URL mutlaka /mcp ile bitmeli:

https://turkiye-energy-mcp-production.up.railway.app/mcp

Kök domain (...railway.app) 404 döner; Claude bunu “sign-in service” hatası olarak gösterebilir. Railway Variables içine şunu ekleyin ve redeploy edin:

PUBLIC_BASE_URL=https://turkiye-energy-mcp-production.up.railway.app
MCP_TRANSPORT=streamable-http
HOST=0.0.0.0

PUBLIC_BASE_URL Claude'un beklediği OAuth discovery / Dynamic Client Registration uçlarını açar. MCP araçları yine herkese açık kalır; OAuth yalnızca bağlayıcı uyumluluğu içindir.

Claude Code remote HTTP:

claude mcp add --transport http turkiye-energy https://turkiye-energy-mcp-production.up.railway.app/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.

• Yıllık ve aylık dosyalar sabit yıla kilitlenmez; en yeni yayın ve en güncel dönem otomatik seçilir. latest_available_period ve data_freshness her yanıtta yer alır.

• Cari aylık değerler TEİAŞ tarafından geçici olabilir (provisional).

• 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, en güncel yıllık denge çalışma kitabının kapsadığı yıllarla 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.