Weather MCP Server 🌦️

---

<a name="türkçe"></a>

Türkçe

OpenWeatherMap API kullanarak gerçek zamanlı hava durumu verisi sağlayan Model Context Protocol (MCP) sunucusu.

Claude Desktop ile entegre ederek, sohbet sırasında doğrudan hava durumu sorgulayabilirsiniz!

✨ Özellikler

• 🌍 Güncel Hava Durumu: Herhangi bir şehir için anlık hava durumu
• 📅 24 Saatlik Tahmin: Detaylı saatlik hava tahmini
• 🌡️ Esnek Birim Sistemi: Metrik (°C) veya Imperial (°F) desteği
• 💨 Kapsamlı Bilgiler: Sıcaklık, nem, rüzgar, basınç, gün doğumu/batımı
• 🚀 Kolay Kurulum: Dakikalar içinde kullanıma hazır

📋 Gereksinimler

• Node.js 18 veya üzeri (İndir)
• Claude Desktop (İndir)
• OpenWeatherMap API Key (Ücretsiz - Kayıt Ol)

🚀 Kurulum

1️⃣ Projeyi İndirin

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

2️⃣ Bağımlılıkları Yükleyin

npm install

3️⃣ OpenWeatherMap API Key Alın

⚠️ ÖNEMLİ: API key'inizi asla GitHub'a yüklemeyin veya başkalarıyla paylaşmayın!

1. OpenWeatherMap sitesine gidin
2. Sign Up butonuna tıklayıp ücretsiz hesap oluşturun
3. Email adresinizi doğrulayın
4. API Keys sayfasına gidin
5. Varsayılan API key'i kopyalayın veya yeni bir tane oluşturun

Not: API key'in aktif olması 1-2 saat sürebilir.

4️⃣ Ortam Değişkenlerini Ayarlayın

.env dosyası oluşturun:

Windows (PowerShell):

copy .env.example .env
notepad .env

macOS/Linux:

cp .env.example .env
nano .env

Dosyayı açıp API key'inizi ekleyin:

OPENWEATHER_API_KEY=buraya_api_keyinizi_yapiştirin

Kaydedin ve kapatın.

5️⃣ Projeyi Derleyin

npm run build

Bu komut TypeScript kodunu JavaScript'e çevirecek ve dist/ klasörüne kaydedecektir.

🖥️ Claude Desktop ile Entegrasyon

1️⃣ Claude Desktop'ı İndirin ve Kurun

Eğer henüz kurulu değilse:

1. Claude Desktop İndir sayfasına gidin
2. İşletim sisteminiz için uygun versiyonu indirin
3. Kurulumu tamamlayın ve uygulamayı açın
4. Hesabınızla giriş yapın

2️⃣ Config Dosyasını Bulun Eğer Dosya Yoksa Oluşturun

Config dosyasının konumu işletim sistemine göre değişir:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Dosyayı açmak için:

1. Win + R tuşlarına basın
2. %APPDATA%\Claude yazıp Enter'a basın
3. claude_desktop_config.json dosyasını Not Defteri veya VS Code ile açın

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

3️⃣ MCP Server'ı Ekleyin

Config dosyasını açtığınızda içinde başka ayarlar olabilir veya boş olabilir.

Eğer dosya boş veya sadece {} varsa, tüm içeriği şununla değiştirin:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "BURAYA_TAM_YOLU_YAZIN/weather-mcp/dist/index.js"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "buraya_api_keyinizi_yazin"
      }
    }
  }
}

Eğer dosyada zaten başka MCP server'lar varsa, sadece "weather" kısmını mcpServers içine ekleyin:

{
  "mcpServers": {
    "existing-server": {
      ...
    },
    "weather": {
      "command": "node",
      "args": [
        "BURAYA_TAM_YOLU_YAZIN/weather-mcp/dist/index.js"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "buraya_api_keyinizi_yazin"
      }
    }
  }
}

Tam Yol Nasıl Bulunur?

Windows:

cd weather-mcp
cd

Çıktı: D:\Projeler\weather-mcp gibi bir şey olacak. Sonuna \dist\index.js ekleyin.

NOT: Windows'ta \ karakterini \\ olarak yazmalısınız:

"D:\\Projeler\\weather-mcp\\dist\\index.js"

macOS/Linux:

pwd

Çıktı: /Users/kullanici/weather-mcp. Sonuna /dist/index.js ekleyin.

4️⃣ Claude Desktop'ı Yeniden Başlatın

ÖNEMLİ: Claude Desktop'ı tamamen kapatın:

1. Pencereyi kapatın
2. Sistem tepsisinden (sağ alt köşe / üst menü çubuğu) de çıkış yapın
3. Tekrar açın

🎯 Kullanım

Claude Desktop açıldıktan sonra, chat kutusuna şu tarz sorular yazın:

Örnek Sorgular

İstanbul'un hava durumu nasıl?

Ankara'da şu an kaç derece?

New York'un 24 saatlik hava tahmini nedir?

Londra'da yarın hava nasıl olacak?

Tokyo'nun hava durumunu Fahrenheit cinsinden göster

🛠️ Geliştirme

Watch Mode (Otomatik Derleme)

Kod değişikliklerinde otomatik derleme için:

npm run dev

Manuel Test

MCP server'ı doğrudan çalıştırıp test edebilirsiniz:

# Windows
set OPENWEATHER_API_KEY=your_api_key_here
npm start

# macOS/Linux
export OPENWEATHER_API_KEY=your_api_key_here
npm start

---

<a name="english"></a>

English

A Model Context Protocol (MCP) server providing real-time weather data using the OpenWeatherMap API.

Integrate with Claude Desktop to ask about the weather directly in your chat!

✨ Features

• 🌍 Current Weather: Instant weather conditions for any city
• 📅 24-Hour Forecast: Detailed hourly weather forecast
• 🌡️ Flexible Units: Support for Metric (°C) or Imperial (°F)
• 💨 Comprehensive Info: Temperature, humidity, wind, pressure, sunrise/sunset
• 🚀 Easy Setup: Ready to use in minutes

📋 Requirements

• Node.js 18 or higher (Download)
• Claude Desktop (Download)
• OpenWeatherMap API Key (Free - Sign Up)

🚀 Installation

1️⃣ Clone the Project

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

2️⃣ Install Dependencies

npm install

3️⃣ Get OpenWeatherMap API Key

⚠️ IMPORTANT: Never upload your API key to GitHub or share it with others!

1. Go to OpenWeatherMap
2. Click Sign Up to create a free account
3. Verify your email address
4. Go to API Keys page
5. Copy the default API key or create a new one

Note: It may take 1-2 hours for the API key to become active.

4️⃣ Set Environment Variables

Create a .env file:

Windows (PowerShell):

copy .env.example .env
notepad .env

macOS/Linux:

cp .env.example .env
nano .env

Open the file and add your API key:

OPENWEATHER_API_KEY=your_api_key_here

Save and close.

5️⃣ Build the Project

npm run build

This command will compile TypeScript code to JavaScript into the dist/ folder.

🖥️ Integration with Claude Desktop

1️⃣ Download and Install Claude Desktop

If not already installed:

1. Go to Claude Desktop Download page
2. Download the appropriate version for your OS
3. Complete installation and open the app
4. Log in with your account

2️⃣ Locate or Create Config File

The config file location depends on your OS:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

To open:

1. Press Win + R
2. Type %APPDATA%\Claude and press Enter
3. Open claude_desktop_config.json with Notepad or VS Code

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

3️⃣ Add MCP Server

If the file is empty or only {}, replace content with:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "FULL_PATH_TO/weather-mcp/dist/index.js"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

If you already have other MCP servers, add "weather" inside mcpServers:

{
  "mcpServers": {
    "existing-server": {
      ...
    },
    "weather": {
      "command": "node",
      "args": [
        "FULL_PATH_TO/weather-mcp/dist/index.js"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

How to Find Full Path?

Windows:

cd weather-mcp
cd

Output: Something like D:\Projects\weather-mcp. Append \dist\index.js.

NOTE: On Windows, you must escape backslashes \ as \\:

"D:\\Projects\\weather-mcp\\dist\\index.js"

macOS/Linux:

pwd

Output: /Users/user/weather-mcp. Append /dist/index.js.

4️⃣ Restart Claude Desktop

IMPORTANT: Completely close Claude Desktop:

1. Close the window
2. Exit from system tray (bottom right / top menu bar)
3. Open again

🎯 Usage

Once Claude Desktop is open, ask questions like:

Example Queries

What is the weather in Istanbul?

What is the temperature in Ankara right now?

What is the 24-hour forecast for New York?

How will the weather be in London tomorrow?

Show Tokyo weather in Fahrenheit

🛠️ Development

Watch Mode (Auto-compile)

To automatically compile on code changes:

npm run dev

Manual Testing

You can run and test the MCP server directly:

# Windows
set OPENWEATHER_API_KEY=your_api_key_here
npm start

# macOS/Linux
export OPENWEATHER_API_KEY=your_api_key_here
npm start