suraj0223/weather-mcp
If you are the rightful owner of weather-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Weather MCP Server is a Model Context Protocol server designed to provide weather data using Spring AI. It offers both MCP and REST API endpoints for accessing weather forecasts and alerts.
getWeatherForecastByLocation
Returns a human-readable multi-day forecast for the supplied coordinates.
getAlerts
Returns active alerts for the supplied US state (two-letter code).
Weather MCP Server
A Model Context Protocol (MCP) server for weather data using Spring AI.
🚀 Quick Start
# Build the JAR file first
./mvnw clean package
# Start the MCP server
docker-compose up
# The server will be available at:
# - HTTP: http://localhost:8080
# - MCP Endpoint: http://localhost:8080/sse
# - Health: http://localhost:8080/actuator/health
🔌 Cursor Integration
Add to your ~/.cursor/mcp.json
:
{
"mcpServers": {
"weather": {
"command": "<ABSOLUTE_PATH_OF_REPO_ON_LOCAL_MACHINE>/weather/start-mcp-server.sh"
}
}
}
🛠️ Available Tools
getWeatherForecastByLocation(latitude, longitude)
- Get weather forecastgetAlerts(state)
- Get weather alerts for US states
🐳 Docker Commands
# Build the JAR (required before running docker-compose)
./mvnw clean package
# Start in background
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down
# Rebuild and start
./mvnw clean package && docker-compose up --build
🧑💻 Development
Prerequisites
- Java 21 (e.g. OpenJDK 21 or Temurin 21)
- Maven 3.9+
- Docker & Docker Compose
Build Locally
# Compile & run unit tests
./mvnw clean verify
# Build the runnable JAR (output in target/)
./mvnw clean package
Run Locally
# Run with the JVM directly
java -jar target/weather-0.0.1-SNAPSHOT.jar
# Or use Spring Boot devtools for hot-reload
./mvnw spring-boot:run
# Or run with Docker Compose
./mvnw clean package && docker-compose up
The server starts on http://localhost:8080
by default.
Environment Variables
Name | Default | Description |
---|---|---|
SERVER_PORT | 8080 | HTTP port to bind |
SPRING_AI_MCP_SERVER_STDIO | false | Run the MCP server over stdio (useful for editor integrations) |
SPRING_PROFILES_ACTIVE | (none) | Comma-separated list of Spring profiles |
Variables can be defined in src/main/resources/application.yml
, overridden via -D
flags, or exported in your shell.
📡 API Reference
This project exposes two flavours of API:
- MCP Tool Endpoints – consumed by supporting IDEs (e.g. Cursor).
- REST Endpoints – ordinary HTTP endpoints that you can call with
curl
, Postman, etc.
MCP Tools
Tool | Signature | Description |
---|---|---|
getWeatherForecastByLocation | (latitude: number, longitude: number) | Returns a human-readable multi-day forecast for the supplied co-ordinates. |
getAlerts | (state: string) | Returns active alerts for the supplied US state (two-letter code). |
REST Endpoints
Method | Path | Example |
---|---|---|
GET | /forecast?lat={lat}&lon={lon} | /forecast?lat=37.7749&lon=-122.4194 |
GET | /alerts/{state} | /alerts/CA |
Note: the REST layer simply proxies to the same service methods backing the MCP tools.