Weather Bridge MCP

Weather Bridge MCP

OpenWeatherMap のリアルタイムの気象データを AI エージェントに橋渡しする、Spring Boot 製の Model Context Protocol (MCP) サーバーです。Claude Desktop または Claude Code に接続すると、英語で天気について質問できます。エージェントが適切なツールを自動的に呼び出します。

"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

---

アーキテクチャ

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 ツール

ツール	説明	パラメーター
getCurrentWeather	都市の現在の気象状況	city — 例："London"
getForecast	複数日間の天気予報	city、days（1～5）

どちらのツールも、AI モデルが応答を作成するために使う、人が読みやすい形式の概要を返します。

---

クイックスタート

Docker を使用する場合（Java は不要です）：

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

Claude Desktop に接続する — ~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

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

Claude Desktop を再起動して、次のように質問します：「ニューヨークの天気は？」

Claude Code（CLI）のセットアップ手順については、claude-config/README.md を参照してください。

---

はじめに（Docker を使用しない場合）

前提条件

• Java 21+
• Maven 3.9+
• 無料の OpenWeatherMap API キー

設定

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

または、プロパティを直接設定します：

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

実行

mvn spring-boot:run

サーバーが起動していることを確認します：

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

ツールの手動テスト（MCP クライアントは不要です）：

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

---

仕組み

リクエストの流れ

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

アプリケーションのコンポーネント

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")]

データモデル

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

---

プロジェクト構成

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

---

開発

# 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

---

環境変数

変数	必須	説明
OPENWEATHERMAP_API_KEY	はい	openweathermap.org の API キー

---

リソース

• Model Context Protocol（MCP）ドキュメント
• Spring AI MCP サーバーリファレンス
• OpenWeatherMap API ドキュメント
• Claude Desktop MCP ガイド

---

ライセンス

MIT © 2025 mm-camelcase