weather-mcp-server

canergulsoyy/weather-mcp-server

3.1

If you are the rightful owner of weather-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Weather MCP Server is a comprehensive system that provides weather data to LLM clients using the Model Context Protocol (MCP).

Tools
2
Resources
0
Prompts
0

🌤️ Weather MCP Server

TypeScript Node.js MCP OpenRouter

Model Context Protocol (MCP) kullanarak hava durumu verilerini LLM istemcilerine sunan kapsamlı bir sistem. Hem standalone MCP server hem de akıllı LLM client içerir.

📋 İçindekiler

✨ Özellikler

🔧 MCP Server

  • get_weather_by_date - Belirli şehir ve tarih için hava durumu
  • health_check - Sunucu sağlık kontrolü
  • Stdio Transport - Cursor, Claude Code vb. ile uyumlu
  • Open-Meteo Integration - Gerçek zamanlı hava durumu verisi

🤖 LLM Client

  • Doğal Dil Desteği - Türkçe soru-cevap
  • OpenRouter Integration - gpt-oss-20b:free (ücretsiz)
  • Akıllı Tool Seçimi - Otomatik MCP tool discovery
  • Interactive CLI - Kullanıcı dostu arayüz

🌍 Weather API

  • Geocoding - Şehir isimlerini koordinatlara çevirme
  • Daily Forecast - Günlük hava durumu tahmini
  • Multi-language - Türkçe dil desteği
  • Free Tier - Tamamen ücretsiz API

🚀 Hızlı Başlangıç

Gereksinimler

  • Node.js 18.18.0+
  • npm veya yarn
  • OpenRouter API Key (ücretsiz)

1. Repository'yi Klonlayın

git clone https://github.com/canergulsoy/mcp-weather-server.git
cd mcp-weather-server

2. Bağımlılıkları Yükleyin

npm install

3. MCP Server'ı Derleyin

npm run build

4. Environment Variables Ayarlayın

# .env dosyası oluşturun
cp env.example .env

# OpenRouter API key'inizi ekleyin
echo "OPENROUTER_API_KEY=your_actual_api_key" >> .env

5. LLM Client'ı Çalıştırın

npm run client:dev

🔑 OpenRouter API Key Alımı

  1. OpenRouter sitesine gidin
  2. Ücretsiz hesap oluşturun
  3. API key alın (günlük 10M token ücretsiz)
  4. .env dosyasına ekleyin

💡 Avantajlar:

  • ✅ Tamamen ücretsiz (günlük 10M token)
  • ✅ GPT-4 kalitesinde yanıtlar
  • ✅ Hızlı response time
  • ✅ OpenAI uyumlu API

📦 Kurulum

Development Mode

# Build olmadan çalıştırma
npm run dev

Production Mode

# Derlenmiş versiyon
npm run start

Client Development

# LLM Client development
npm run client:dev

# Client build
npm run client:build

# Client production
npm run client:start

🎯 Kullanım

MCP Server (Standalone)

# Server'ı başlatın
node dist/index.js

# Başka bir MCP client ile bağlanın
# (Cursor, Claude Code, vb.)

LLM Client (Interactive)

# Interactive CLI başlatın
npm run client:dev

# Örnek soru:
🤔 Sorunuz: 29.08.2025 tarihinde İstanbul'da hava nasıl olacak?

Programmatic Usage

import { WeatherLLMClient } from './dist/client/weather-client.js';

const client = new WeatherLLMClient('./dist/index.js');
await client.initialize();

const response = await client.processQuestion(
    "Yarın Berlin'de hava nasıl olacak?"
);
console.log(response);

🔌 Cursor/Claude Entegrasyonu

MCP Server Konfigürasyonu

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/abs/path/to/dist/index.js"]
    }
  }
}

Development Mode (Build olmadan)

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "tsx", "/abs/path/to/src/index.ts"]
    }
  }
}

📚 API Dokümantasyonu

Tool: get_weather_by_date

Belirli bir şehir ve tarih için günlük hava durumu bilgisi döndürür.

Parametreler:

  • city (string, zorunlu): Şehir adı (örn: "İstanbul")
  • country (string, opsiyonel): Ülke kodu (örn: "TR")
  • date (string, zorunlu): Tarih (YYYY-MM-DD formatında)

Örnek Kullanım:

// MCP Client
const result = await mcpClient.callTool({
    name: "get_weather_by_date",
    arguments: {
        city: "İstanbul",
        country: "TR",
        date: "2025-08-29"
    }
});

Response Format:

{
  "content": [
    {
      "type": "text",
      "text": "Şehir: İstanbul\nTarih: 2025-08-29\nEn yüksek: 28.1°C\nEn düşük: 21.6°C\nYağış toplamı: 0 mm\nKod: 2"
    }
  ]
}

Tool: health_check

Sunucunun çalışır durumda olduğunu doğrular.

Parametreler: Yok

Response:

{
  "content": [
    {
      "type": "text",
      "text": "OK"
    }
  ]
}

🏗️ Proje Yapısı

mcp-weather-server/
├── src/
│   ├── index.ts              # MCP Server ana dosyası
│   ├── openmeteo.ts         # Weather API entegrasyonu
│   └── client/
│       ├── index.ts         # Interactive CLI
│       └── weather-client.ts # LLM Client sınıfı
├── dist/                    # Derlenmiş dosyalar
├── docs/                    # Dokümantasyon
├── examples/                # Kullanım örnekleri
├── tests/                   # Test dosyaları
├── package.json            # Proje konfigürasyonu
├── tsconfig.json          # TypeScript konfigürasyonu
├── .env.example           # Environment variables örneği
├── README.md              # Bu dosya
└── LICENSE                # MIT Lisansı

🧪 Test ve Geliştirme

Test Script'leri

# Type checking
npm run typecheck

# Client test
npm run test:client

# Build test
npm run build

Development Workflow

# 1. Code değişiklikleri
# 2. Type checking
npm run typecheck

# 3. Build
npm run build

# 4. Test
npm run test:client

# 5. Commit & Push
git add .
git commit -m "feat: yeni özellik eklendi"
git push origin main

🔧 Environment Variables

VariableAçıklamaVarsayılanZorunlu
OPENROUTER_API_KEYOpenRouter API key-✅
OPENROUTER_BASE_URLOpenRouter API endpointhttps://openrouter.ai/api/v1❌
MCP_SERVER_PATHMCP Server dosya yolu./dist/index.js❌

📊 Performance Metrikleri

  • Tool Discovery: ~50ms
  • Weather API Call: ~200-500ms
  • LLM Processing: ~1-3s
  • Total Response: ~2-4s
  • Memory Usage: ~50-100MB
  • Daily Token Limit: 10M (ücretsiz)

🚀 Gelecek Geliştirmeler

Kısa Vadeli

  • Caching mekanizması
  • Rate limiting
  • Daha fazla hava durumu tool'u
  • Batch processing

Orta Vadeli

  • Web interface
  • Database integration
  • User preferences
  • Historical data

Uzun Vadeli

  • Machine learning predictions
  • Multi-language support
  • Advanced analytics
  • Mobile app

🤝 Katkıda Bulunma

Bu projeye katkıda bulunmak istiyorsanız:

  1. Fork yapın
  2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
  3. Commit yapın (git commit -m 'feat: amazing feature')
  4. Push yapın (git push origin feature/amazing-feature)
  5. Pull Request oluşturun

Geliştirme Kuralları

  • TypeScript strict mode kullanın
  • ESLint kurallarına uyun
  • Test coverage'ı koruyun
  • Commit message'ları conventional commits formatında yazın

Kod Standartları

// ✅ Doğru
export class WeatherClient {
    private readonly apiKey: string;
    
    constructor(apiKey: string) {
        this.apiKey = apiKey;
    }
}

// ❌ Yanlış
export class weatherclient {
    private apikey: string;
    
    constructor(apikey: string) {
        this.apikey = apikey;
    }
}

📄 Lisans

Bu proje altında lisanslanmıştır.

👨‍💻 Geliştirici

Caner Gülsoy tarafından geliştirilmiştir.

🙏 Teşekkürler

📞 İletişim