Weather MCP

Weather MCP Server

A Model Context Protocol (MCP) server for weather data using Spring AI.

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

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.

🚀 Quick Start

Build the JAR (required before running docker-compose)

./mvnw clean package