Weather MCP App

Weather MCP App

<p align="center"> <img src="https://img.shields.io/badge/Version-0.0.1-blue" alt="Version"> <img src="https://img.shields.io/badge/License-MIT-green" alt="License"> <img src="https://img.shields.io/badge/TypeScript-5.9+-3178c6" alt="TypeScript"> <img src="https://img.shields.io/badge/React-19-61dafb" alt="React"> </p>

A Model Context Protocol (MCP) server with an interactive React UI for fetching weather data. Works with Claude Desktop, ChatGPT, and any MCP-compatible client.

Features

• Current Weather - Real-time temperature, feels-like, humidity, wind speed/direction
• Hourly Forecast - 24-hour forecast with weather icons
• 7-Day Forecast - Daily high/low temperatures and conditions
• Air Quality - US AQI, PM2.5, PM10, and ozone levels
• Unit Toggle - Switch between Celsius and Fahrenheit
• Dual Transport - Works with stdio (Claude Desktop) and HTTP (ChatGPT)
• Rate Limiting - 100/hour, 1000/day, 30000/month

Installation

# Clone the repository
git clone <repository-url>
cd weather-mcp-app

# Install dependencies
npm install

# Build the project
npm run build

Quick Start

Claude Desktop (Stdio)

# Run with stdio transport
npm run start:stdio

ChatGPT (HTTP)

# Run HTTP server (listens on http://localhost:3001/mcp)
npm run start

# Or in development with hot reload
npm run dev

Configuration

Claude Desktop

Add to your Claude Desktop settings (~/Library/Application Support/Claude/settings.json):

{
  "mcpServers": {
    "weather-mcp-app": {
      "command": "npx",
      "args": ["-y", "weather-mcp-app", "--stdio"]
    }
  }
}

Or if running locally:

{
  "mcpServers": {
    "weather-mcp-app": {
      "command": "node",
      "args": ["path/to/weather-mcp-app/dist/main.js", "--stdio"]
    }
  }
}

ChatGPT

Use the HTTP endpoint: http://localhost:3001/mcp

Usage

Tool: get_weather

name: get_weather
description: Get current weather, hourly forecast, 7-day forecast, and air quality for a city name or zip code.

Input Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | location | string | Yes | City name (e.g., "London") or zip code (e.g., "10001,US") | | unit | string | No | "celsius" or "fahrenheit" (default: "celsius") |

Example Request

{
  "name": "get_weather",
  "arguments": {
    "location": "San Francisco, CA",
    "unit": "celsius"
  }
}

Example Response

{
  "content": [
    {
      "type": "text",
      "text": "Weather in San Francisco:\nMainly clear, 18°C\nFeels like 17°C\nHumidity: 65%\nWind: WNW 15 km/h\nAir Quality: Good (AQI: 35)\n\nHourly Forecast:\nNow: 18°C ☀️\n1PM: 19°C 🌤️\n...\n\n7-Day Forecast:\nToday: 15° - 20°, Mainly clear\nTue: 14° - 19°, Partly cloudy\n..."
    }
  ],
  "structuredContent": {
    "current": { ... },
    "hourly": [ ... ],
    "daily": [ ... ],
    "location": { ... },
    "airQuality": { ... }
  }
}

Project Structure

weather-mcp-app/
├── src/
│   ├── api/
│   │   └── weather-client.ts      # Open-Meteo API client
│   ├── constants/
│   │   └── weather.ts             # Weather codes & utilities
│   ├── handlers/
│   │   └── weather-handler.ts    # MCP tool handler
│   ├── services/
│   │   └── weather-formatter.ts   # Text formatting
│   ├── types/
│   │   └── weather.ts             # Zod schemas & types
│   ├── errors/
│   │   └── index.ts              # Custom errors
│   ├── utils/
│   │   └── logger.ts             # Logging utilities
│   ├── components/ui/            # shadcn/ui components
│   ├── App.tsx                   # Main React UI
│   ├── server.ts                  # MCP server setup
│   ├── main.ts                    # Entry point
│   └── config.ts                  # Configuration
├── dist/                          # Built output
│   ├── main.js                    # Compiled server
│   └── mcp-app.html              # Compiled UI
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | HTTP server port | 3001 | | NODE_ENV | Environment mode | development | | ALLOWED_ORIGINS | CORS origins (production) | - |

Development Commands

# Build the project
npm run build

# Build server only
npm run build:server

# Run with stdio transport
npm run start:stdio

# Run with HTTP server
npm run start

# Development mode with watch
npm run dev

# Type checking
npm run typecheck

# Run tests
npm run test

# Run unit tests
npm run test:unit

# Run e2e tests
npm run test:e2e

API Reference

Uses free Open-Meteo APIs (no API key required):

• Geocoding: https://geocoding-api.open-meteo.com/v1/search
• Weather: https://api.open-meteo.com/v1/forecast
• Air Quality: https://air-quality-api.open-meteo.com/v1/air-quality

Security

• HSTS headers enabled in production
• CORS restricted to localhost in development
• Request body limit: 10KB
• Input validation with Zod schemas
• Rate limiting on all requests
• Structured logging with Pino

Changelog

See CHANGELOG.md for detailed changes.

Acknowledgments

• Open-Meteo API - Free weather and air quality data API. This project uses their Geocoding, Weather Forecast, and Air Quality APIs.
• MCP Apps SDK - For enabling interactive UI capabilities in MCP servers.
• shadcn/ui - For the beautiful and accessible React components.
• Lucide - For the icon library.

License

MIT