Weather Bridge MCP

A Spring Boot Model Context Protocol (MCP) server that bridges live weather data from OpenWeatherMap to AI agents. Connect it to Claude Desktop or Claude Code and ask weather questions in plain English — the agent calls the right tool automatically.

"What's the weather in Tokyo?" → getCurrentWeather("Tokyo") → 18°C, partly cloudy
"3-day forecast for Berlin?"   → getForecast("Berlin", 3)  → Mon 12°C, Tue 10°C, Wed 14°C

---

Architecture

graph TB
    subgraph dev["Developer Environment"]
        U(["👤 Developer"])
        CL["Claude Desktop\n/ Claude Code"]
        MC["MCP Client"]
        U -->|natural language| CL
        CL <--> MC
    end

    subgraph server["Weather Bridge MCP  —  Spring Boot :8080"]
        direction TB
        SSE["SSE Transport\n/sse"]
        SRV["MCP Server\n(auto-configured)"]
        TP["WeatherService\n@Tool methods"]
        RT["RestTemplate"]
        SSE --> SRV --> TP --> RT
    end

    OWM[("☁️ OpenWeatherMap\nREST API")]

    MC  -->|"SSE connection"| SSE
    RT  -->|"HTTPS"| OWM

---

MCP Tools

Tool	Description	Parameters
getCurrentWeather	Current conditions for a city	city — e.g. "London"
getForecast	Multi-day forecast	city, days (1–5)

Both tools return a human-readable summary that the AI model uses to compose its response.

---

Quick Start

With Docker (no Java needed):

git clone https://github.com/mm-camelcase/weather-bridge-mcp.git
cd weather-bridge-mcp
cp .env.example .env           # add your OPENWEATHERMAP_API_KEY
docker-compose up

Connect Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "weather-bridge": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Restart Claude Desktop and ask: "What's the weather in New York?"

See claude-config/README.md for Claude Code (CLI) setup instructions.

---

Getting Started (without Docker)

Prerequisites

• Java 21+
• Maven 3.9+
• A free OpenWeatherMap API key

Configuration

cp .env.example .env
# edit .env — set OPENWEATHERMAP_API_KEY=your_key_here
export $(cat .env | xargs)

Or set the property directly:

mvn spring-boot:run -Dopenweathermap.api-key=your_key_here

Run

mvn spring-boot:run

Verify the server is up:

curl http://localhost:8080/weather/health
# → {"status":"UP","service":"weather-bridge-mcp"}

Manual tool testing (no MCP client needed):

curl "http://localhost:8080/weather/current/London"
curl "http://localhost:8080/weather/forecast/Paris?days=3"

---

How It Works

Request Flow

sequenceDiagram
    actor Dev as 👤 Developer
    participant Claude as Claude Desktop
    participant Client as MCP Client
    participant Server as Weather Bridge MCP
    participant API as OpenWeatherMap

    Dev->>Claude: "What's the weather in Tokyo?"
    Claude->>Client: tool call: getCurrentWeather("Tokyo")
    Client->>Server: SSE POST /mcp/message
    Server->>API: GET /weather?q=Tokyo&units=metric
    API-->>Server: JSON payload
    Server-->>Client: formatted weather summary
    Client-->>Claude: tool result
    Claude-->>Dev: "Tokyo is 18°C, partly cloudy with light winds..."

Application Components

graph LR
    subgraph app["Spring Boot Application"]
        direction TB
        MAIN["WeatherBridgeMcpApplication\n@SpringBootApplication"]
        TCP["ToolCallbackProvider\nMethodToolCallbackProvider"]
        WS["WeatherService\n@Tool getCurrentWeather\n@Tool getForecast"]
        WC["WeatherController\nREST /weather/**"]
        GEH["GlobalExceptionHandler\n@RestControllerAdvice"]
        RT["RestTemplate"]

        MAIN --> TCP
        MAIN --> RT
        TCP --> WS
        WS --> RT
        WC --> WS
    end

    subgraph infra["Auto-configured by spring-ai-starter-mcp-server-webmvc"]
        SSE["SSE Transport\n/sse"]
        MCPSRV["MCP Server"]
        SSE --> MCPSRV --> TCP
    end

    RT --> OWM[("☁️ OpenWeatherMap")]

Data Model

classDiagram
    class WeatherData {
        +String name
        +List~WeatherCondition~ weather
        +MainData main
        +Wind wind
        +Clouds clouds
        +Sys sys
        +Integer visibility
    }
    class MainData {
        +double temp
        +double feelsLike
        +double tempMin
        +double tempMax
        +int humidity
        +int pressure
    }
    class ForecastData {
        +List~ForecastItem~ list
        +City city
    }
    class ForecastItem {
        +MainData main
        +List~WeatherCondition~ weather
        +Wind wind
        +String dtTxt
    }

    WeatherData "1" --> "1" MainData
    WeatherData "1" --> "0..*" WeatherCondition
    ForecastData "1" --> "1..*" ForecastItem
    ForecastItem "1" --> "1" MainData

---

Project Structure

weather-bridge-mcp/
├── src/main/java/com/example/weatherbridgemcp/
│   ├── WeatherBridgeMcpApplication.java   # Entry point + bean definitions
│   ├── service/
│   │   └── WeatherService.java            # @Tool methods + OpenWeatherMap client
│   ├── model/
│   │   ├── WeatherData.java               # Current weather response model
│   │   └── ForecastData.java              # Forecast response model
│   ├── controller/
│   │   └── WeatherController.java         # REST endpoints for manual testing
│   └── exception/
│       ├── WeatherServiceException.java
│       └── GlobalExceptionHandler.java
├── src/main/resources/
│   ├── application.properties             # Server + MCP + API configuration
│   └── application-dev.properties         # Debug logging profile
├── src/test/                              # Unit tests (MockRestServiceServer)
├── claude-config/                         # Claude Desktop / Claude Code setup
├── Dockerfile                             # Multi-stage build
├── docker-compose.yml
└── .github/workflows/ci.yml               # GitHub Actions

---

Development

# Run tests (no API key needed — uses MockRestServiceServer)
mvn test

# Build a fat JAR
mvn clean package -DskipTests

# Run with debug logging
mvn spring-boot:run -Dspring.profiles.active=dev

---

Environment Variables

Variable	Required	Description
OPENWEATHERMAP_API_KEY	Yes	API key from openweathermap.org

---

Resources

• Model Context Protocol (MCP) Documentation
• Spring AI MCP Server Reference
• OpenWeatherMap API Documentation
• Claude Desktop MCP Guide

---

License

MIT © 2025 mm-camelcase