turkiye-energy-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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:
https://www.teias.gov.tr/api/galleryhttps://webim.teias.gov.tr/file/{media_slug}?download
HTML scraping production veri yolunda kullanılmaz; tek istisna aşağıdaki YTBS senkronizasyonudur. 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.
YTBS (TEİAŞ Yük Tevzi Bilgi Sistemi) — geçici işletme verisi
ytbsbilgi.teias.gov.tr İstatistikler sayfası, lisanssız üretim dahil 15 dk yük ve kaynak
bazlı üretimi ile günlük Excel raporunu (saatlik enerji dengesi, depolama, ithalat/ihracat,
kuruluş × kaynak kurulu güç, emre amade kapasite, ulusal/bölgesel puant, su durumu) yayımlar.
Kaynak resmî bir API değildir (JSF form gönderimi) ve yalnız Türkiye IP'lerinden yanıt
verir. Bu yüzden veri MCP sunucusu tarafından değil, Türkiye'deki bir makinede çalışan
ytbs-sync komutuyla çekilir ve aylık bölümlenmiş CSV deposuna yazılır:
pip install -e .
ytbs-sync # bugün dahil son 7 gün (revizyonları da yakalar)
ytbs-sync --baslangic 2026-01-01 --bitis 2026-03-31 --veri-klasoru D:\ytbs-veri
git clone -b ytbs-data --single-branch https://github.com/emresoykan/turkiye-energy-mcp D:\ytbs-veri
ytbs-sync --veri-klasoru D:\ytbs-veri --git-push # veriyi ytbs-data dalına gönderirVeri bu reponun yalnız veri içeren ytbs-data dalında tutulur; main dalına ve deploy'a
karışmaz. --git-push kimlik doğrulamayı makinenin git yapılandırmasına (Windows'ta Git
Credential Manager) bırakır; script token saklamaz. Railway'deki sunucu
YTBS_DATA_REPO=emresoykan/turkiye-energy-mcp ve YTBS_DATA_REF=ytbs-data ile okur; repo
public olduğu için token gerekmez. CSV'ler bu nedenle GitHub'da herkese açıktır (kaynak
zaten kamuya açık TEİAŞ verisidir).
Depo yerleşimi: <klasör>/<tablo>/<YYYY>/<YYYY-MM>.csv + manifest.json. Her satır tarih
(rapor günü) ve cekim_zamani taşır. TEİAŞ'a göre veriler geçicidir, geriye dönük
düzeltilir ve lisanssız üretim ay sonuna kadar tahminidir. 15 dk yük serisi anlık talep
(MW) değeridir; saatlik enerji için saatlik_denge (MWh) kullanılmalıdır.
Zaman damgaları: 15 dk serisinde zaman dilimin bitişini gösterir; bir günün ilk
noktası 00:15, son noktası ertesi günün 00:00'ıdır ve önceki günün tarih'i altında
durur (YTBS'nin 24:00 etiketi bu biçime çevrilir). Saatlik tablolarda (saatlik_denge,
emre_amade) saat saat-sonu etiketidir; zaman_baslangic ise dilimin başlangıcıdır
(saat 01:00 → zaman_baslangic 00:00). İki seriyi birleştirirken bu farkı hesaba
katın.
Related MCP server: mcp-server-eia
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
├── ytbs/ # YTBS istemcisi, ayrıştırıcılar, CSV deposu, ytbs-sync CLI
├── 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.AsyncClientPydantic 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]'
pytestBağımlılık kilidi
pyproject.toml yalnız alt sınır + major üst sınır verir (ör. mcp>=2,<3;
server.py yalnız 2.x SDK'da bulunan mcp.server.MCPServer'ı kullanır).
Docker imajı, test edilmiş tam sürümleri içeren constraints.txt ile kurulur
(pip install -c constraints.txt .), böylece build'ler tekrarlanabilir. Aynı
sürümleri yerelde kurmak için: pip install -c constraints.txt -e '.[dev]'.
Kilidi yenilemek (bağımlılık eklendiğinde veya sürüm yükseltirken):
uv pip compile pyproject.toml --python-version 3.12 --python-platform linux \
--no-header --no-annotate --upgrade -o constraints.txt
pip install -c constraints.txt -e '.[dev]' && pytestDosyanın başındaki yorum satırlarını koruyun; Python sürümü Dockerfile'daki
taban imajla (python:3.12-slim) aynı olmalıdır. Testler geçmeden yeni kilidi
commit etmeyin.
Çalıştırma
Streamable HTTP:
MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 turkiye-energy-mcpMCP endpoint:
http://localhost:8000/mcpHealth endpoint:
http://localhost:8000/health
stdio:
MCP_TRANSPORT=stdio turkiye-energy-mcpEnvironment variables
Değişken | Varsayılan | Açıklama |
|
| HTTP bind adresi |
|
| HTTP portu; Railway otomatik sağlar |
|
| JSON log seviyesi |
|
|
|
|
| Streamable HTTP yolu |
|
| Kaynak timeout |
|
| İlk deneme dışındaki retry sınırı |
|
| Exponential backoff çarpanı |
| proje user-agent'i | Resmî kaynağa gönderilen kimlik |
|
| Günlük veri cache süresi |
|
| Aylık veri cache süresi |
|
| Yıllık veri cache süresi |
|
| Santral cache süresi |
| resmî TEİAŞ URL | JSON katalog kökü |
| resmî TEİAŞ dosya URL | Dosya indirme kökü |
| boş | Claude connector OAuth discovery origin'i (ör. Railway domain) |
| boş | OAuth token'larını imzalayan HMAC anahtarı ( |
|
|
|
| boş | Tanımlıysa |
| boş |
|
| boş | CSV deposunun GitHub reposu, |
|
| Veri reposunun dalı |
| boş | Yalnız private veri reposunda gerekir; yalnız okuma yetkili fine-grained token |
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 upRailway'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>/mcpMCP tool'ları
Toplam 23 production tool vardır (16 teias_*/EÜAŞ + 7 ytbs_*).
Tool | Parametreler | Veri |
|
| Aylık üretim, talep, ithalat/ihracat ve kaynak üretimi |
|
| Yıllık kaynak bazlı brüt üretim |
|
| Yıllık kaynak bazlı kurulu güç |
|
| Ani/saatlik puant ve brüt talep |
|
| Toplam/ülke bazlı ithalat ve ihracat |
|
| Gerilim bazlı hatlar ve trafolar |
|
| Yenilenebilir kapasite/üretim ve paylar |
|
| Yıllık elektrik sistemi özeti |
|
| EÜAŞ hidro/termik portföyü |
|
| Ada göre santral detayı |
|
| EÜAŞ kurulu güç serisi |
|
| EÜAŞ yıllık üretimi |
|
| EÜAŞ aylık üretimi |
|
| EÜAŞ/Türkiye kapasite payı |
|
| EÜAŞ/Türkiye üretim payı |
|
| İki üretim serisinin karşılaştırması |
|
| 15 dk anlık yük ve kaynak bazlı üretim, MW (≤7 gün) |
|
| Saatlik üretim, depolama, ithalat/ihracat, tüketim, MWh (≤92 gün) |
|
| Günlük üretim, kaynak veya kuruluş kırılımı (≤366 gün) |
|
| Günlük kurulu güç ve santral sayısı (kaynak/kuruluş/detay) |
|
| Saatlik emre amade kapasite, talep tahmini, arz güvenliği (≤31 gün) |
|
| Ulusal puant rekorları veya 9 bölgenin puantı (≤92 gün) |
| — | YTBS deposunun son senkronu, kapsadığı günler, hatalar |
ytbs_* tool'ları ytbs-sync deposundan okur; yanıtlarda provisional: true,
missing_days, storage_backend ve last_synced_at (deponun son senkron zamanı)
metadata alanları bulunur. data_freshness provisional'dır; istenen günlerden biri
depoda yoksa partial olur. sources/source/items
YTBS kaynak kodlarını (ör. ruzgar, barajli, akarsu, dogalgaz), Türkçe yazımlarını
veya İngilizce karşılıklarını (wind, solar, natural_gas ...) kabul eder; bilinmeyen
bir ad (ör. hydro: YTBS barajlı/akarsu ayrımı yapar) sessizce düşürülmez, geçerli
adları listeleyen INVALID_PARAMETER döner.
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/mcpKö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.0PUBLIC_BASE_URL Claude'un beklediği OAuth discovery / Dynamic Client Registration
uçlarını açar. OAuth yalnızca bağlayıcı uyumluluğu içindir; verdiği token'lar /mcp
erişimini kısıtlamaz. MCP_API_KEY tanımlı değilse MCP araçları URL'i bilen herkese
açıktır; erişimi kısıtlamak için aşağıdaki API anahtarını kullanın.
Erişim Güvenliği (API Anahtarı)
Veri kamuya açık olsa da, koruma olmadan URL'i bilen herkes bu deployment üzerinden
TEİAŞ/GitHub'a istek attırabilir ve Railway kaynaklarını tüketebilir. MCP_API_KEY
ayarlandığında MCP transport'u (/mcp ve açık listede olmayan her yol) eşleşen bir
X-API-Key header'ı ister (sabit zamanlı karşılaştırma). Açık kalan yollar yalnızca tam
eşleşmeyle şunlardır: /health (Railway health check header göndermez), / ve OAuth
uçları (/.well-known/* discovery, /register, /authorize, /token) — Claude
discovery sırasında özel header göndermez. /mcp/, //mcp, /%6Dcp veya OPTIONS
gibi varyasyonlar da anahtar ister. Değişken boşsa auth devre dışıdır ve sunucu log'a
uyarı basar.
Kesintisiz devreye alma sırası — ters sırada yaparsanız connector arada 401 alır:
Bu kodu deploy edin (
MCP_API_KEYhenüz tanımsız → auth kapalı, hiçbir şey bozulmaz).Anahtarı üretin:
openssl rand -hex 32Claude connector ayarlarında Add header ile
X-API-Key= üretilen değeri girin. Connector hâlâ çalışır; sunucu bu header'ı şimdilik yok sayar. Claude Code için:claude mcp add --transport http turkiye-energy <url>/mcp --header "X-API-Key: <anahtar>"Railway'de
MCP_API_KEYdeğişkenini aynı değerle tanımlayın. Servis yeniden başladığı anda auth devreye girer ve connector zaten header'ı gönderiyordur.
Anahtar sızarsa 2-4. adımları yeni bir değerle tekrarlayın; URL'i değiştirmek veya connector'ı silip yeniden kurmak gerekmez.
Railway her deploy'da servisi yeniden başlatır: OAUTH_SIGNING_KEY tanımlı değilse OAuth
token'ları da her deploy'da geçersizleşir ve connector yeniden yetkilendirme ister. Bunu
önlemek için OAUTH_SIGNING_KEY değişkenini de (openssl rand -hex 32) sabit bir değerle
tanımlayın.
Claude Code remote HTTP:
claude mcp add --transport http turkiye-energy https://turkiye-energy-mcp-production.up.railway.app/mcpClaude 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
Veri seti | Resmî sayfa | Sıklık | Derinlik |
Aylık üretim/talep | Aylık | 2019-günümüz (katalogdan dinamik) | |
Kaynak bazlı üretim | Yıllık | En güncel yıllık galerideki seri | |
Kaynak bazlı kurulu güç | aynı | Yıllık | En güncel yıllık galerideki seri |
Puant/talep | aynı | Yıllık | En güncel yıllık galerideki seri |
Dış ticaret/ülkeler | aynı | Yıllık | En güncel yıllık denge tablosu |
İletim hatları | aynı | Yıllık | En güncel yıllık galerideki seri |
Trafolar | aynı | Yıllık | En güncel yıllık galerideki seri |
EÜAŞ santral portföyü | aynı, EÜAŞ konulu TEİAŞ tabloları | Yıllık | En güncel yıllık rapor dönemi |
EÜAŞ kurulu güç | aynı | Yıllık | En güncel yıllık galerideki seri |
EÜAŞ üretim | aynı | Yıllık | En güncel yıllık galerideki seri |
Test ve smoke test
Ana testler internet kullanmaz:
pytestGerçek resmî endpoint ve 16 production veri yolu:
python scripts/smoke_test.pySmoke 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_periodvedata_freshnessher yanıtta yer alır.Cari aylık değerler TEİAŞ tarafından geçici olabilir (
provisional).Saatlik tüketim ve 15 dk yük eğrisi yalnız YTBS'den (
ytbs-sync) gelir; kaynak Türkiye dışından erişilemez ve sayfa yapısı değişirse ayrıştırıcı açık hata verir.Ü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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Official Microsoft MCP Server to query Microsoft Entra data using natural language
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for trivia: 1.4M+ questions (EN+PL), 24 categories, 12 tools + 4 prompts, OAuth 2.1.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceA read-only MCP server that exposes European day-ahead electricity prices for ~41 bidding zones via tools like hourly prices, cheapest hours, current price, and cross-zone summary, enabling AI agents to query energy market data.1-
- FlicenseAqualityDmaintenanceAn MCP server that exposes the U.S. Energy Information Administration (EIA) Open Data API, enabling LLMs to browse and query energy data across 17 datasets with generic, composable tools.4-
- AlicenseAqualityCmaintenanceMCP server that unifies official Turkish open data sources into a single interface, letting AI agents query and compare normalized indicators like population, inflation, and GDP through natural language.10MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that wraps the U.S. Energy Information Administration's Open Data API, enabling assistants to fetch live energy data via natural language. It provides tools for querying series, browsing data routes, filtering facets, and running custom queries.MIT