hall9zeha/WeatherMCPServer

WeatherMCPServer

Spring Boot server created with IntelliJ IDEA to expose weather and air quality services using the OpenWeatherMap API, ready for integration with language models and MCP (Model Context Protocol) agents.

Description

OpenWeatherMCPServer provides REST endpoints and tools compatible with Spring AI and MCP to query weather information, air quality, UV index, geographic coordinates, and more, facilitating integration with language models such as GPT, Claude, etc.

Main Features

• Query current weather by city or coordinates (Tool: getWeatherByCity, getWeatherByCoordinates).
• Extended forecast (OneCall) by coordinates (Tool: getWeatherOneCall).
• Air quality index (AQI) query by coordinates (Tool: getAirQualityIndex).
• UV index query by coordinates (Tool: getUvIndex).
• Conversion between city name and geographic coordinates (Tool: getCoordinatesByCity, getCityByCoordinates).
• Historical weather query by coordinates and timestamp (Tool: getHistoricalWeather).
• Structured responses in POJOs ready for serialization/deserialization.
• Ready integration for MCP agents and Spring AI.

Requirements

• Java 21
• Gradle
• OpenWeatherMap API Key (free or paid)

Main Dependencies

• Spring Boot 3.5.5
• Spring AI MCP Server WebMVC Starter
• OpenWeatherMap API
• Lombok
• JSON

Installation

1. Clone the repository:

   git clone https://github.com/hall9zeha/WeatherMCPServer
   cd OpenWeatherMCPServer
   

2. You can add your OpenWeatherMap API Key in src/main/resources/application.properties:

   openweathermap.api.key=YOUR_API_KEY
   

Warning: Do not share your private keys (API keys) in files or repositories. Use them only for local testing and, for greater security, always manage your keys through environment variables.

3. Build the executable JAR file. You can do this with the following command:

   #Linux/Mac/Windows
   ./gradlew bootJar
   

4. Run the generated JAR, passing your OpenWeatherMap API key as an environment variable:

   #Linux/Mac
   java -Dopenweathermap.api.key=YOUR_API_KEY -jar build/libs/OpenWeatherMCPServer-0.0.1-SNAPSHOT.jar
   

   #Windows powerShell
   $env:OWN_API_KEY="YOUR_API_KEY"
   java -jar build/libs/OpenWeatherMCPServer-0.0.1-SNAPSHOT.jar
   

   Replace YOUR_API_KEY with your actual OpenWeatherMap key. This will start your server using the local (STDIO) configuration. If you want to switch between local (STDIO) and remote (web) mode, remember to modify the comments in the application.properties file as instructed there.

Configuration for Different Deployment Modes

The application.properties file allows you to configure the server to work as:

1. Remote server (Web, recommended for production)

• Leave the following lines commented:

  #spring.main.web-application-type=none
  #spring.ai.mcp.server.stdio=true
  #spring.main.banner-mode=off
  

• The server will work as a REST web API accessible from any remote language model client.
• The exposed SSE endpoint will be /mcp/weather.

2. Local server with STDIO transport (for direct integration with local agents)

• Uncomment the following lines in application.properties:

  spring.main.web-application-type=none
  spring.ai.mcp.server.stdio=true
  spring.main.banner-mode=off
  

• This disables the web server and enables communication via standard input/output (STDIO), useful for local MCP agents.

Note: Don't forget to comment or uncomment these lines according to the desired usage mode before starting the server.

Integration with Language Models

The server is ready to be consumed by MCP agents and language models compatible with Spring AI, allowing tool chaining and automatic reasoning over weather data.

Configuration and Usage with Claude Desktop

You can consume this server directly from Claude Desktop using MCP integration. For this, the JAR package must already be generated and you must add the following configuration in the developer configuration file of Claude Desktop (for example, claude_desktop_config.json). Then restart Claude Desktop and it will start the server locally and communicate with it via the MCP protocol and STDIO transport.

{
  "mcpServers": {
    "openweather-mcp-local": {
      "command": "java",
      "args": [
        "-Dspring.main.web-application-type=none",
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.ai.mcp.server.type=SYNC",
        "-Dspring.main.banner-mode=off",
        "-Dlogging.pattern.console=",
        "-Dopenweathermap.api.key=YOUR_API_KEY",
        "-jar",
        "D:\\YOUR\\DIRECTORY\\PATH\\WeatherMCPServer-main\\build\\libs\\OpenWeatherMCPServer-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

• Replace YOUR_API_KEY with your actual OpenWeatherMap key.
• Modify the JAR path to the actual location on your system.

With this configuration, Claude Desktop will be able to invoke the tools of the OpenWeatherMCPServer locally using the MCP protocol and STDIO transport, allowing tool chaining and automatic reasoning over weather and air quality data.

Example of Use with Claude Desktop

Tools from our MCP server that Claude Desktop will use

Weather forecast by city name

Air quality index and UV radiation index

Licence

Designed and developed by hall9zeha (Barry Zea H.) 2025

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Author

Barry Zea H.