weather-mcp

suraj0223/weather-mcp

3.2

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.

Tools
  1. getWeatherForecastByLocation

    Returns a human-readable multi-day forecast for the supplied coordinates.

  2. 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 forecast
  • getAlerts(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

NameDefaultDescription
SERVER_PORT8080HTTP port to bind
SPRING_AI_MCP_SERVER_STDIOfalseRun 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:

  1. MCP Tool Endpoints – consumed by supporting IDEs (e.g. Cursor).
  2. REST Endpoints – ordinary HTTP endpoints that you can call with curl, Postman, etc.

MCP Tools

ToolSignatureDescription
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

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