MCP Weather Server

A streamable HTTP MCP (Model Context Protocol) server for getting weather data via the Open-Meteo API.

🚀 Features

• Streamable HTTP Transport: Compatible with MCP 2025-03-26 specification
• Session Management: Support for persistent sessions with unique IDs
• Weather Tools: Three main tools for geolocation and weather data
• REST API: Health endpoint for monitoring

📦 Installation

# Clone and install dependencies
npm install

# Compile TypeScript
npm run build

# Start the server
npm start

🔧 Configuration

The server uses the following environment variables:

• PORT: Listening port (default: 3000)

Example:

PORT=8080 npm start

🛠️ Available MCP Tools

1. search_location

Search for GPS coordinates of a city or location by name.

Parameters:

• city_name (string): Name of the city or location to search for
• country (string, optional): Country name to narrow the search
• limit (number, optional): Maximum number of results to return (default: 5, max: 10)

Example response:

{
  "query": "Paris",
  "country_filter": null,
  "total_results": 5,
  "locations": [
    {
      "name": "Paris",
      "country": "France",
      "admin1": "Île-de-France",
      "latitude": 48.8566,
      "longitude": 2.3522,
      "timezone": "Europe/Paris",
      "population": 2161000,
      "elevation": 42
    },
    {
      "name": "Paris",
      "country": "United States",
      "admin1": "Texas",
      "latitude": 33.6609,
      "longitude": -95.5555,
      "timezone": "America/Chicago",
      "population": 25171,
      "elevation": 177
    }
  ]
}

2. get_weather

Get current weather information for a location.

Parameters:

• latitude (number): Latitude in decimal degrees (-90 to 90)
• longitude (number): Longitude in decimal degrees (-180 to 180)
• location_name (string, optional): Optional location name for display

Example response:

{
  "location": "Paris",
  "weather": {
    "current_weather": {
      "temperature": 15.2,
      "windspeed": 10.5,
      "winddirection": 230,
      "weathercode": 1,
      "is_day": 1,
      "time": "2024-01-15T14:00"
    },
    "current_units": {
      "temperature": "°C",
      "windspeed": "km/h",
      "winddirection": "°",
      "weathercode": "wmo code",
      "is_day": "",
      "time": "iso8601"
    }
  },
  "lastUpdate": "2024-01-15T14:05:30.123Z"
}

3. stream_weather

Start streaming weather data with periodic updates.

Parameters:

• latitude (number): Latitude in decimal degrees (-90 to 90)
• longitude (number): Longitude in decimal degrees (-180 to 180)
• location_name (string, optional): Optional location name for display
• interval_seconds (number, default: 60): Update interval in seconds

🌐 HTTP Endpoints

Server Health

GET /health

Returns server status:

{
  "status": "OK",
  "timestamp": "2024-01-15T14:05:30.123Z"
}

MCP Endpoint

POST /mcp
GET /mcp  
DELETE /mcp

Main endpoint for MCP communications. Supports:

• POST: Initialization and request sending
• GET: SSE stream establishment for responses
• DELETE: Session termination

📋 Usage Example with MCP Client

1. Session Initialization

const initRequest = {
  jsonrpc: '2.0',
  id: 1,
  method: 'initialize',
  params: {
    protocolVersion: '2024-11-05',
    capabilities: { tools: {} },
    clientInfo: { name: 'weather-client', version: '1.0.0' }
  }
};

const response = await fetch('http://localhost:8080/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream'
  },
  body: JSON.stringify(initRequest)
});

const sessionId = response.headers.get('mcp-session-id');

2. List Available Tools

const listToolsRequest = {
  jsonrpc: '2.0',
  id: 2,
  method: 'tools/list',
  params: {}
};

const response = await fetch('http://localhost:8080/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify(listToolsRequest)
});

3. Call Weather Tool

const weatherRequest = {
  jsonrpc: '2.0',
  id: 3,
  method: 'tools/call',
  params: {
    name: 'get_weather',
    arguments: {
      latitude: 48.8566,
      longitude: 2.3522,
      location_name: 'Paris'
    }
  }
};

const response = await fetch('http://localhost:8080/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify(weatherRequest)
});

🧪 Testing

To test the server:

# Start the server
PORT=8080 npm start

# In another terminal, test the health endpoint
curl http://localhost:8080/health

🔍 Using MCP Inspector

You can use the official MCP Inspector to visually explore and test your weather server tools in a user-friendly interface.

Installation and Setup

1. Install MCP Inspector (requires Node.js):

   npx @modelcontextprotocol/inspector
   

2. Start your weather server:

   PORT=8080 npm start
   

3. Configure MCP Inspector:

   • Server URL: http://localhost:8080/mcp
   • Transport: HTTP (Streamable)
   • Protocol Version: 2024-11-05

Visual Interface Features

The MCP Inspector provides:

• 🛠️ Tools Explorer: Browse all available tools (search_location, get_weather, stream_weather)
• 📝 Interactive Forms: Easy-to-use forms for entering tool parameters
• 🎯 Real-time Testing: Execute tools and see live responses
• 📊 Response Viewer: JSON-formatted results with syntax highlighting
• 🔄 Session Management: Visual session state and connection status
• 📈 Request/Response History: Track all your API interactions

Example Workflow

1. Connect to your server using the Inspector
2. Explore the three available weather tools
3. Test location search:
   • Tool: search_location
   • Parameters: city_name: "Paris"
4. Get weather data:
   • Tool: get_weather
   • Parameters: Use coordinates from previous search
5. Monitor streaming:
   • Tool: stream_weather
   • Watch real-time weather updates

Benefits

• No coding required: Test your MCP server without writing client code
• Visual debugging: See exactly what data flows between client and server
• Tool validation: Verify parameter schemas and response formats
• Rapid prototyping: Quickly iterate on your MCP server implementation

The Inspector is particularly useful during development to ensure your weather server works correctly before integrating it into larger applications.

🏗️ Architecture

• Express.js: HTTP server
• MCP SDK: MCP protocol implementation with StreamableHTTPServerTransport
• Open-Meteo API: Weather data source
• TypeScript: Development language with compilation to JavaScript

📄 Specifications

• MCP Protocol: Version 2024-11-05 and 2025-03-26
• Transport: Streamable HTTP with SSE support
• Data Format: JSON-RPC 2.0
• Weather API: Open-Meteo

🔗 Useful Links

• Model Context Protocol
• Open-Meteo API
• MCP TypeScript SDK

📝 License

This project is a demonstration example based on open-meteo-mcp.