# MCP Weather Server

A lightweight, self‑hosted **Model Context Protocol (MCP) server** that exposes your weather‑forecast API as MCP tools.  
This allows LLMs and agent frameworks to call your weather data directly through a standardized interface.

Clients run this server inside their own environment and connect it to their preferred MCP‑compatible LLM (e.g., Claude Desktop, Cursor, etc.).

---

## 🚀 Features

- MCP‑compatible WebSocket server  
- Tools for:
  - Current weather by latitude/longitude  
  - Multi‑day forecast  
- JSON Schema–validated tool inputs  
- Simple configuration via environment variables  
- No external dependencies required to run the server (beyond Node.js)  
- Ready for Docker, CI, and cloud deployment  


---

## 🛠️ Requirements

- Node.js 20+
- A valid API key for your weather service
- Access to your weather API base URL

---

## ⚙️ Configuration

Copy the example environment file:

bash
cp .env.example .env


Then edit \`.env\`:


WEATHER_API_KEY=your_api_key_here
WEATHER_API_URL=https://api.yourweather.com
PORT=3001
LOG_LEVEL=info

---

## ▶️ Running the Server

### Development mode

bash
npm run dev

### Build & run

bash
npm run build
npm start


The server will start on:
ws://localhost:3001

---

## 🌤️ Available MCP Tools

### \`getCurrentWeather\`

Retrieve current weather conditions for a specific latitude/longitude.

**Input:**

json
{
  "lat": 38.9,
  "lon": -77.0
}


**Output (example):**

json
{
  "summary": "Current weather at (38.9, -77)",
  "data": { ... }
}

---

### \`getForecast\`

Retrieve a multi‑day forecast for a location.

**Input:**

json
{
  "lat": 38.9,
  "lon": -77.0,
  "days": 5
}


**Output (example):**

json
{
  "summary": "5‑day forecast for (38.9, -77)",
  "data": { ... }
}


---

## 🧪 Testing

bash
npm test


---

## 🐳 Docker (Optional)

A Dockerfile is included.

Build:
bash
docker build -t mcp-weather-server .


Run:
bash
docker run -p 3001:3001
  -e WEATHER_API_KEY=your_api_key
  -e WEATHER_API_URL=https://api.yourweather.com
  mcp-weather-server


---

## 🔒 Security Notes

- Host this server inside your network or VPC  
- Protect access with firewall rules or mTLS if exposing externally  
- Rotate API keys regularly  
- Avoid exposing your weather API key in logs or client‑side code  

---

## 📄 License

MIT License.  
Feel free to fork, modify, and integrate into your own systems.

---

## 🤝 Contributing

Pull requests and issues are welcome.  
If you extend the toolset or add new weather endpoints, feel free to contribute back.