MCP Sunucusu

Bu kılavuz geliştiriciler ve teknik bilgiye sahip kullanıcılar içindir. MCP sunucusunu kurabilmek için Node.js, terminal kullanımı ve yapılandırma dosyaları hakkında temel bilgi gerekmektedir.

57 Araç

iklim.co API”sinin tüm yetenekleri MCP aracı olarak sunulur — yıldırım, fırtına, yağış, tahmin, alarmlar ve daha fazlası.

Otomatik Auth

JWT token”lar otomatik olarak alınır ve yenilenir. Kimlik bilgilerinizi girin, gerisini sunucu halleder.

HMAC İmzalı

Her istek HMAC-SHA256 ile imzalanır. Kimlik bilgileri düz metin olarak iletilmez; istek başına tekil nonce ile replay saldırıları engellenir.

Genel Bakış

iklim.co MCP Sunucusu, Model Context Protocol standardını uygular ve iklim.co REST API’sinin tamamını 9 kategoride 57 araç olarak sunar. MCP uyumlu herhangi bir yapay zeka istemcisi (Claude, OpenClaw vb.) doğal dil aracılığıyla canlı hava durumu verileri sorgulayabilir, alarmları yönetebilir ve kullanıcı hesaplarını kontrol edebilir.

Kategori	Araç Sayısı	Kapsam
⚡ Yıldırım	2	Yıldırım çarpma verileri
🌪️ Fırtına	3	Fırtına hücresi takibi
🌧️ Yağış	2	Radar yağış verileri
🌤️ Tahmin	3	Saatlik / günlük / anlık hava durumu
👤 Auth & Kullanıcı	11	Kimlik doğrulama ve kullanıcı yönetimi
🏢 Hesap	8	Hesap ve abonelik yönetimi
📍 Nokta Alarmları	6	GPS tabanlı uyarı abonelikleri
🗺️ Coğrafi Alarmlar	12	Sınır bazlı uyarılar + il/ilçe/mahalle kataloğu
📅 Tahmin Alarmları	10	Eşik bazlı tahmin uyarıları + il/ilçe kataloğu
Toplam	57

Gereksinimler

Node.js >= 18 (ES2022 desteği gerekli)
npm >= 9
iklim.co API erişim bilgileri: HMAC secret, kullanıcı adı ve şifre

Kurulum

Kaynak kod git.tarla.io/iklim.co/mcp-server adresindeki public repository’den indirilebilir.

git clone https://git.tarla.io/iklim.co/mcp-server.git
cd mcp-server
npm install
npm run build

Ortam Değişkenleri

Sunucu başlamadan önce aşağıdaki değişkenlerin tanımlı olması gerekir. Geliştirme ortamında mcp-server dizininde bir .env dosyası oluşturabilirsiniz (.gitignore kapsamında):

# .env
IKLIM_ENV=test                     # prod | test | local  (IKLIM_BASE_URL yoksa kullanılır)
IKLIM_BASE_URL=                    # Opsiyonel. Tanımlıysa IKLIM_ENV'i override eder
IKLIM_HMAC_SECRET=<secret>         # Zorunlu. İstek imzalama için HMAC-SHA256 anahtarı
IKLIM_USERNAME=<email>             # Zorunlu. API hesabı e-postası
IKLIM_PASSWORD=<password>          # Zorunlu. API hesabı şifresi
IKLIM_TOKEN_STORE_PATH=            # Opsiyonel. Access/refresh token'ları kalıcı saklamak için dosya yolu
IKLIM_HTTP_LOG_PATH=               # Opsiyonel. API istek log dosyası yolu
IKLIM_HTTP_LOG_MAX_BYTES=5242880   # Opsiyonel. Rotate eşiği (byte), varsayılan: 5 MB
IKLIM_HTTP_LOG_MAX_FILES=5         # Opsiyonel. Tutulacak rotated dosya sayısı
IKLIM_HTTP_LOG_REQUEST_BODY_MAX_BYTES=16384   # Opsiyonel. Request body log boyut sınırı
IKLIM_HTTP_LOG_RESPONSE_BODY_MAX_BYTES=16384  # Opsiyonel. Response body log boyut sınırı

Ortama göre base URL:

`IKLIM_ENV`	URL
`prod`	`https://api.iklim.co`
`test`	`https://api-test.iklim.co`
`local`	`http://localhost:8080`

IKLIM_HTTP_LOG_PATH tanımlıysa her API çağrısı tek satır JSON olarak loglanır. Hassas alanlar (Authorization, X-Signature, password, token vb.) otomatik olarak maskelenir.

Build ve Çalıştırma

# TypeScript'i derle (dist/ klasörünü oluşturur)
npm run build

# Derlenmiş sunucuyu başlat
npm start

# Geliştirme modunda çalıştır — derleme adımı gerekmez
npm run dev

Başarılı başlatmada çıktı:

iklim.co MCP server running

Sunucu stdio transportu üzerinden iletişim kurar. Doğrudan terminalde çalıştırmak yerine bir MCP istemcisi tarafından yönetilmesi beklenir.

MCP İstemci Konfigürasyonu

Claude CLI (`.mcp.json`)

Proje kök dizinine bir .mcp.json dosyası ekleyin. Claude CLI bunu otomatik olarak yükler:

{
  "mcpServers": {
    "iklim": {
      "command": "node",
      "args": ["/tam/yol/mcp-server/dist/index.js"],
      "env": {
        "IKLIM_ENV": "test",
        "IKLIM_HMAC_SECRET": "<secret>",
        "IKLIM_USERNAME": "<email>",
        "IKLIM_PASSWORD": "<password>"
      }
    }
  }
}

Global olarak tanımlamak için aynı mcpServers bloğunu ~/.claude/settings.json dosyasına ekleyin.

OpenClaw

openclaw mcp set komutu env parametresini ayrı olarak desteklemez; tüm alanları tek bir JSON nesnesi olarak geçirin:

openclaw mcp set iklim '{"type":"stdio","command":"node","args":["/tam/yol/mcp-server/dist/index.js"],"env":{"IKLIM_ENV":"test","IKLIM_HMAC_SECRET":"<secret>","IKLIM_USERNAME":"<email>","IKLIM_PASSWORD":"<password>"}}'

Ya da ~/.openclaw/openclaw.json dosyasını doğrudan düzenleyin:

{
  "mcp": {
    "iklim": {
      "type": "stdio",
      "command": "node",
      "args": ["/tam/yol/mcp-server/dist/index.js"],
      "env": {
        "IKLIM_ENV": "test",
        "IKLIM_HMAC_SECRET": "<secret>",
        "IKLIM_USERNAME": "<email>",
        "IKLIM_PASSWORD": "<password>"
      }
    }
  }
}

Diğer MCP İstemcileri

MCP stdio standardını destekleyen her istemci bağlanabilir. Gerekli parametreler:

Parametre	Değer
`transport`	`stdio`
`command`	`node`
`args`	`["<dist/index.js tam yolu>"]`
`env`	Yukarıdaki dört değişken

Araç Kataloğu

⚡ Yıldırım

Araç	Açıklama
`get_lightnings_within`	Merkez koordinatı ve yarıçap ile tanımlanan dairesel alan içindeki yıldırım çarpmalarını sorgular
`get_lightnings_page`	Zaman aralığına göre yıldırım verilerini sayfalı olarak getirir

🌪️ Fırtına

Araç	Açıklama
`get_thunderstorms_within`	Dairesel alan içindeki fırtına hücrelerini sorgular
`get_thunderstorms_page`	Zaman aralığına göre fırtına verilerini sayfalı getirir
`get_thunderstorm_details`	`eventId` ile belirli bir fırtına olayının geçmiş detaylarını getirir

🌧️ Yağış

Araç	Açıklama
`get_precipitations_within`	Dairesel alan içindeki radar yağış verilerini sorgular; `intensityThreshold` ile filtrelenebilir
`get_precipitations_page`	Zaman aralığına göre yağış verilerini sayfalı getirir; `intensityThreshold` zorunludur

Yoğunluk seviyeleri (en düşükten en yükseğe): DRIZZLE < LIGHT < MODERATE < HEAVY < VERY_HEAVY < EXTREME

🌤️ Hava Tahmini

Araç	Açıklama
`get_hourly_forecast`	1–14 günlük saatlik tahminler; 53 seçilebilir metrik desteklenir
`get_daily_forecast`	Günlük agregat tahminler; saatlik ile aynı parametreler (solar panel alanları hariç)
`get_current_weather`	Koordinat için en güncel hava gözlemini getirir

53 desteklenen tahmin metriği

WEATHER_ICON, TEMPERATURE, APPARENT_TEMPERATURE, DEW_POINT_TEMPERATURE, HUMIDITY, CLOUD_COVER, CLOUD_COVER_LOW, CLOUD_COVER_MID, CLOUD_COVER_HIGH, WIND_SPEED, WIND_GUST, WIND_DIRECTION, WIND_SPEED_AT_100M, WIND_DIRECTION_AT_100M, PRECIPITATION, RAIN, SHOWERS, SNOWFALL, SNOW_DEPTH, PRECIPITATION_PROBABILITY, WEATHER_CODE, PRESSURE_MSL, SURFACE_PRESSURE, VISIBILITY, EVAPOTRANSPIRATION, ET0_FAO_EVAPOTRANSPIRATION, VAPOUR_PRESSURE_DEFICIT, CAPE, LIFTED_INDEX, CONVECTIVE_INHIBITION, SUNSHINE_DURATION, SHORTWAVE_RADIATION, DIRECT_RADIATION, DIFFUSE_RADIATION, DIRECT_NORMAL_IRRADIANCE, GLOBAL_TILTED_IRRADIANCE, TERRESTRIAL_RADIATION, SHORTWAVE_RADIATION_INSTANT, DIRECT_RADIATION_INSTANT, DIFFUSE_RADIATION_INSTANT, DIRECT_NORMAL_IRRADIANCE_INSTANT, GLOBAL_TILTED_IRRADIANCE_INSTANT, TERRESTRIAL_RADIATION_INSTANT, SOIL_TEMPERATURE_0CM, SOIL_TEMPERATURE_6CM, SOIL_TEMPERATURE_18CM, SOIL_TEMPERATURE_54CM, SOIL_MOISTURE_0_TO_1CM, SOIL_MOISTURE_1_TO_3CM, SOIL_MOISTURE_3_TO_9CM, SOIL_MOISTURE_9_TO_27CM, SOIL_MOISTURE_27_TO_81CM, IS_DAY

👤 Auth & Kullanıcı

Araç	Açıklama
`auth_register`	Yeni kullanıcı hesabı oluşturur
`auth_logout`	Geçerli JWT token’ı geçersiz kılar
`user_get_me`	Oturum açmış kullanıcının profilini getirir
`user_get`	`userId` ile kullanıcı detayını getirir
`user_create`	(Admin) `roles` ve `status` ile yeni kullanıcı oluşturur
`user_update`	(Admin) `userId` ile kullanıcı alanlarını günceller
`user_list`	Sayfalı kullanıcı listesi; `roles` ve `status` ile filtrelenebilir
`user_unblock`	Bloke edilmiş kullanıcıyı açar
`user_change_password`	`oldPassword` ve `newPassword` ile şifre değiştirir
`user_password_reset_request`	Şifre sıfırlama e-postası gönderir
`user_password_reset`	Sıfırlama token’ı ile şifreyi günceller

🏢 Hesap

Araç	Açıklama
`account_get`	`userId` ile hesap detaylarını getirir
`account_create`	Yeni hesap oluşturur (`INDIVIDUAL` veya `ORGANIZATION`)
`account_update`	`accountId` ile hesap alanlarını günceller
`account_activation_request`	Aktivasyon e-postası gönderir
`account_activate`	E-posta doğrulama token’ı ile hesabı aktive eder
`account_phone_activation_request`	SMS doğrulama kodu gönderir
`account_activate_phone`	SMS token’ı ile telefonu doğrular
`account_update_subscription`	Abonelik planını değiştirir

📍 Nokta Alarmları

GPS koordinatı ve yapılandırılabilir yarıçap etrafındaki olaylar için uyarı abonelikleri.

Araç	Açıklama
`point_alarm_register`	Yeni nokta alarmı oluşturur
`point_alarm_update`	Mevcut alarmı günceller
`point_alarm_delete`	Alarm kaydını siler
`point_alarm_get_by_id`	Tekil alarm detayını getirir
`point_alarm_get_by_recipient`	Alıcıya ait tüm alarmları listeler
`point_alarm_list`	Sayfalı alarm listesi; `recipientIds` ile filtrelenebilir

🗺️ Coğrafi Alarmlar

İdari sınır, poligon veya H3 adresi bazlı uyarı abonelikleri. Üç sınır tipi desteklenir:

// İdari sınır
{ "type": "ADMINISTRATIVE", "cityId": 6, "districtId": 60 }

// Poligon
{ "type": "POLYGON", "polygon": { "exterior": [{"lat": 39.9, "lng": 32.8}, ...] } }

// H3 hücre indeksi
{ "type": "H3INDEX", "h3Address": "8f2830828052d25" }

CRUD araçları (geo_alarm_register, geo_alarm_update, geo_alarm_delete, geo_alarm_get_by_id, geo_alarm_get_by_recipient, geo_alarm_list) Nokta Alarmları ile aynı imzayı paylaşır. Konum kataloğu:

Araç	Açıklama
`geo_alarm_list_cities`	Tüm illeri listeler
`geo_alarm_get_city`	`cityId` ile il detayını getirir
`geo_alarm_list_districts`	`cityId` ile ilçeleri listeler
`geo_alarm_get_district`	`districtId` ile ilçe detayını getirir
`geo_alarm_list_neighborhoods`	`districtId` ile mahalleleri listeler
`geo_alarm_get_neighborhood`	`neighborhoodId` ile mahalle detayını getirir

📅 Tahmin Alarmları

Eşik aşıldığında sabah 04:00 UTC veya akşam 16:00 UTC’de gönderilen uyarılar. Eşik parametreleri:

Parametre	Değerler
`precipitationThreshold`	mm cinsinden sayısal değer
`snowFallThreshold`	`LIGHT` \| `MODERATE` \| `HEAVY`
`windGustThreshold`	`STRONG_WIND` \| `STORM` \| `SEVERE_STORM` \| `HURRICANE`
`hotTemperatureThreshold`	`HOT_SNAP` \| `HEAVY_HOT_SNAP` \| `EXTREME_HOT_SNAP`
`coldTemperatureThreshold`	`COLD_SNAP` \| `HEAVY_COLD_SNAP` \| `EXTREME_COLD_SNAP`

CRUD araçları Nokta Alarmları ile aynı imzayı takip eder. Ek konum kataloğu araçları: forecast_alarm_list_cities, forecast_alarm_get_city, forecast_alarm_list_districts, forecast_alarm_get_district.

Mimari

src/
├── index.ts          # MCP sunucu başlatma, araç yönlendirme
├── config.ts         # Ortam değişkeni ayrıştırma
├── auth.ts           # JWT token yönetimi (otomatik yenileme)
├── client.ts         # HTTP API istemcisi (HMAC imzalama)
├── security.ts       # HMAC-SHA256, nonce, idempotency key
└── tools/
    ├── lightnings.ts
    ├── thunderstorms.ts
    ├── precipitations.ts
    ├── forecasts.ts
    ├── auth.ts
    ├── accounts.ts
    ├── point-alarms.ts
    ├── geo-alarms.ts
    └── forecast-alarms.ts

İstek akışı:

MCP İstemci
    │
    ▼
index.ts  (CallToolRequestSchema)
    │
    ▼
tools/<kategori>.ts  ← Zod validasyonu
    │
    ▼
client.ts  (apiGet / apiPost / apiPatch / apiDelete)
    │  ├── auth.ts → geçerli JWT al (gerekirse otomatik yenile)
    │  └── security.ts → HMAC-SHA256 imzası üret
    │
    ▼
iklim.co REST API

Kimlik Doğrulama ve Güvenlik

Her API etkileşimi iki bağımsız güvenlik katmanı kullanır: JWT tabanlı kimlik doğrulama ve HMAC-SHA256 istek imzalama. Her ikisi de her isteğe uygulanır.

Otomatik Auth Akışı

Sunucu, ilk araç çağrısında otomatik olarak giriş yapar. Manuel bir login adımı gerekmez.

İlk araç çağrısı
    │
    ▼
getValidAccessToken()          ← auth.ts
    │
    ├─ Token state yok → login()
    │       POST /v1/auth/login  { username, password }
    │       ← { accessToken, refreshToken }
    │       JWT payload decode → son kullanma süresini hesapla
    │       tokenState'e kaydet
    │
    ├─ accessToken süresi dolmak üzere (< 30 sn kaldı) → refresh()
    │       POST /v1/auth/refresh  { refreshToken }
    │       ← { accessToken, refreshToken }
    │       tokenState'i güncelle
    │
    └─ accessToken geçerli → doğrudan döndür

login ve refresh endpoint’leri Authorization: Bearer header’ı içermez — bu istekler yalnızca HMAC imzasıyla doğrulanır.

HTTP İstek Header’ları

Header	Değer	Notlar
`Content-Type`	`application/json`	Sabit
`Authorization`	`Bearer <accessToken>`	Yalnızca normal API isteklerinde; login/refresh’te yer almaz
`X-Signature`	hex string	HMAC-SHA256 imzası
`X-Timestamp`	Unix epoch (ms)	`Date.now()` string olarak
`X-Nonce`	UUID v4	Her istekte tekil — replay saldırısını engeller
`X-Idempotency-Key`	UUID v4	`POST`, `PUT`, `PATCH` ve `DELETE` isteklerinde

HMAC-SHA256 İmza Hesabı

X-Signature değeri dört bileşenin | ile birleştirilmesinin HMAC-SHA256’sıdır:

imzalanacak_veri = "METHOD|PATH_WITH_QUERY|TIMESTAMP|BODY"
X-Signature      = HMAC-SHA256(imzalanacak_veri, IKLIM_HMAC_SECRET) → hex

Örnek — GET isteği:

METHOD    = "GET"
PATH      = "/v1/users?pageNumber=0&pageSize=10"
TIMESTAMP = "1774349677000"
BODY      = ""   ← GET isteğinde body yok

imzalanacak = "GET|/v1/users?pageNumber=0&pageSize=10|1774349677000|"
X-Signature = HMAC-SHA256(imzalanacak, secret) → "a3f9c2..."

Örnek — POST isteği:

METHOD    = "POST"
PATH      = "/v1/lightnings/within"
TIMESTAMP = "1774349677000"
BODY      = '{"center":{"lat":39.87,"lng":32.74},"radius":50000,...}'

imzalanacak = "POST|/v1/lightnings/within|1774349677000|{\"center\":...}"
X-Signature = HMAC-SHA256(imzalanacak, secret) → "7be41d..."

Güvenlik Önerileri

IKLIM_HMAC_SECRET ve IKLIM_PASSWORD değerlerini kaynak koda veya git geçmişine eklemeyin
Üretim ortamında .env dosyası yerine sistem ortam değişkenlerini veya bir secrets manager kullanın
Her ortam için ayrı kimlik bilgileri kullanın (prod / test / local)
HMAC secret’ı düzenli olarak rotate edin

Başlamadan Önce

Webhook Alarmları

Kimlik Doğrulama & Kullanıcılar

Hesaplar

Yıldırım/Şimşek

Fırtına

Yağış

Tahminler

Nokta Alarm API

Coğrafi Alan Alarm API

Tahnin Alarm API

Güzergah Alarm API

57 Araç

Otomatik Auth

HMAC İmzalı

​Genel Bakış

​Gereksinimler

​Kurulum

​Ortam Değişkenleri

​Build ve Çalıştırma

​MCP İstemci Konfigürasyonu

​Claude CLI (.mcp.json)

​OpenClaw

​Diğer MCP İstemcileri

​Araç Kataloğu

​⚡ Yıldırım

​🌪️ Fırtına

​🌧️ Yağış

​🌤️ Hava Tahmini

​👤 Auth & Kullanıcı

​🏢 Hesap

​📍 Nokta Alarmları

​🗺️ Coğrafi Alarmlar

​📅 Tahmin Alarmları

​Mimari

​Kimlik Doğrulama ve Güvenlik

​Otomatik Auth Akışı

​HTTP İstek Header’ları

​HMAC-SHA256 İmza Hesabı

​Güvenlik Önerileri

Genel Bakış

Gereksinimler

Kurulum

Ortam Değişkenleri

Build ve Çalıştırma

MCP İstemci Konfigürasyonu

Claude CLI (`.mcp.json`)

OpenClaw

Diğer MCP İstemcileri

Araç Kataloğu

⚡ Yıldırım

🌪️ Fırtına

🌧️ Yağış

🌤️ Hava Tahmini

👤 Auth & Kullanıcı

🏢 Hesap

📍 Nokta Alarmları

🗺️ Coğrafi Alarmlar

📅 Tahmin Alarmları

Mimari

Kimlik Doğrulama ve Güvenlik

Otomatik Auth Akışı

HTTP İstek Header’ları

HMAC-SHA256 İmza Hesabı

Güvenlik Önerileri