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

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:

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

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.

---