# Weather MCP Server 🌦️

[![Turkish](https://img.shields.io/badge/lang-Türkçe-red.svg)](#türkçe) [![English](https://img.shields.io/badge/lang-English-blue.svg)](#english)

---

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

OpenWeatherMap API kullanarak gerçek zamanlı hava durumu verisi sağlayan [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](https://nodejs.org/))
- **Claude Desktop** ([İndir](https://claude.ai/download))
- **OpenWeatherMap API Key** (Ücretsiz - [Kayıt Ol](https://openweathermap.org/api))

### 🚀 Kurulum

#### 1️⃣ Projeyi İndirin

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

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

```bash
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](https://openweathermap.org/api) sitesine gidin
2. **Sign Up** butonuna tıklayıp **ücretsiz hesap** oluşturun
3. Email adresinizi doğrulayın
4. [API Keys](https://home.openweathermap.org/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):**
```powershell
copy .env.example .env
notepad .env
```

**macOS/Linux:**
```bash
cp .env.example .env
nano .env
```

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

```env
OPENWEATHER_API_KEY=buraya_api_keyinizi_yapiştirin
```

Kaydedin ve kapatın.

#### 5️⃣ Projeyi Derleyin

```bash
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](https://claude.ai/download) 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:

```json
{
  "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:

```json
{
  "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:**
```bash
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:
```json
"D:\\Projeler\\weather-mcp\\dist\\index.js"
```

**macOS/Linux:**
```bash
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:

```bash
npm run dev
```

#### Manuel Test

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

```bash
# 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)](https://modelcontextprotocol.io) 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](https://nodejs.org/))
- **Claude Desktop** ([Download](https://claude.ai/download))
- **OpenWeatherMap API Key** (Free - [Sign Up](https://openweathermap.org/api))

### 🚀 Installation

#### 1️⃣ Clone the Project

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

#### 2️⃣ Install Dependencies

```bash
npm install
```

#### 3️⃣ Get OpenWeatherMap API Key

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

1. Go to [OpenWeatherMap](https://openweathermap.org/api)
2. Click **Sign Up** to create a **free account**
3. Verify your email address
4. Go to [API Keys](https://home.openweathermap.org/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):**
```powershell
copy .env.example .env
notepad .env
```

**macOS/Linux:**
```bash
cp .env.example .env
nano .env
```

Open the file and add your API key:

```env
OPENWEATHER_API_KEY=your_api_key_here
```

Save and close.

#### 5️⃣ Build the Project

```bash
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](https://claude.ai/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:

```json
{
  "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`:

```json
{
  "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:**
```bash
cd weather-mcp
cd
```
Output: Something like `D:\Projects\weather-mcp`. Append `\dist\index.js`.

**NOTE:** On Windows, you must escape backslashes `\` as `\\`:
```json
"D:\\Projects\\weather-mcp\\dist\\index.js"
```

**macOS/Linux:**
```bash
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:

```bash
npm run dev
```

#### Manual Testing

You can run and test the MCP server directly:

```bash
# Windows
set OPENWEATHER_API_KEY=your_api_key_here
npm start

# macOS/Linux
export OPENWEATHER_API_KEY=your_api_key_here
npm start
```