# 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.
