Weather MCP Server

A Quarkus-based Model Context Protocol (MCP) server that provides weather information using the National Weather Service API.

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is a standardized protocol that allows AI models to discover and use external tools. This project implements an MCP server that provides weather forecast and alert tools that can be called by AI models or other MCP clients. The server uses the Quarkiverse MCP Server extension to expose tools as a standard MCP API, making it easier for AI systems to access real-time weather data.

Weather Tools Provided

This server provides two main tools:

1. getAlerts - Retrieves active weather alerts for a specified US state

   {
     "name": "getAlerts",
     "arguments": {
       "state": "CA"  // Two-letter US state code
     }
   }

1. getForecast - Retrieves weather forecast for a geographic location

   {
     "name": "getForecast",
     "arguments": {
       "latitude": 37.7749,  // Latitude coordinate
       "longitude": -122.4194  // Longitude coordinate
     }
   }

Project Structure

• Main class containing tool definitions using annotations Weather.java``@Tool
• REST client to communicate with the National Weather Service API WeatherClient.java
• Formats the raw API responses into human-readable text WeatherFormatter.java
• Model classes for API responses (Alerts, Forecast, etc.)

Getting Started

Prerequisites

• Java 24 or newer
• Maven (for building)
• JBang (for running with MCP Inspector)
• Node.js with npm (for the MCP Inspector)

Running with Maven

# Build and package as uber-jar
./mvnw package
java -jar target/mcp-server-1.0.0-SNAPSHOT-runner.jar

Running with JBang

This project is configured to work with JBang for easy execution. The application.properties includes configuration to build an uber-jar that can be run with JBang:

# Build the uber-jar
./mvnw package

# Run with JBang
jbang org.devgurupk:mcp-server:1.0.0-SNAPSHOT:runner

Authentication (OAuth 2.1)

This MCP server is secured using OAuth 2.1 with Keycloak as the identity provider. It supports both static clients (like Postman) and Dynamic Client Registration (for tools like JetBrains AI Assistant).

Quick Setup

1. Start Keycloak:

   docker compose up -d
   

2. Start the MCP Server:

   mvn quarkus:dev
   

3. Keycloak Admin: http://localhost:8180 (admin/admin)

Test User Credentials

• Username: testuser
• Password: password

Dynamic Client Registration (DCR)

This server supports OAuth 2.0 Dynamic Client Registration, enabling MCP clients like JetBrains AI Assistant and Claude Desktop to automatically register themselves with Keycloak.

Tested with:

• ✅ JetBrains AI Assistant (Antigravity)
• ✅ MCP Inspector
• ✅ Postman

How DCR Works

1. The MCP client discovers the authorization server via /.well-known/oauth-protected-resource
2. Client dynamically registers with Keycloak (no manual client setup needed)
3. User authenticates via Keycloak login
4. Token is validated locally by the Quarkus server

Testing with Postman (OAuth 2.0)

Configure Postman's Authorization tab with these settings:

Steps:

1. Click Get New Access Token
2. Login with testuser / password
3. Click Use Token
4. Connect to http://localhost:8080/mcp/sse

Testing with MCP Inspector

You can use the Model Context Protocol Inspector to test and interact with the MCP server: `

... View full README on GitHub