OpenWeatherMap MCP Server

A Model Context Protocol (MCP) server that provides weather data integration using the OpenWeatherMap API. This server allows Claude, GitHub Copilot, and other MCP clients to fetch current weather conditions, forecasts, and weather alerts for any location worldwide.

Features

• 🌡️ Current Weather: Get real-time weather conditions
• 📅 Weather Forecasts: Hourly (up to 48 hours) and daily (up to 8 days) forecasts
• 🚨 Weather Alerts: Active weather warnings and alerts
• 🗺️ Geocoding: Convert city names and zip codes to coordinates
• 🌍 Multiple Units: Support for metric, imperial, and standard units
• 🗣️ Internationalization: Weather descriptions in multiple languages
• 🧪 Full Test Coverage: Comprehensive test suite with Jest
• 📝 TypeScript: Full type safety and excellent developer experience

Tools Provided

Weather Tools

1. get_current_weather - Get current weather conditions for a location
2. get_hourly_forecast - Get hourly forecast for up to 48 hours
3. get_daily_forecast - Get daily forecast for up to 8 days
4. get_weather_alerts - Get active weather alerts for a location

Geocoding Tools

5. geocode_location - Convert location names to coordinates
6. geocode_zipcode - Convert zip/postal codes to coordinates

Prerequisites

• OpenWeatherMap API key with One Call API 3.0 subscription
• Node.js 18+ (for development only)

Installation

You can use this MCP server directly via NPX without needing to clone or build locally:

npx @tristau/openweathermap-mcp

For development or local modifications, see the Development section below.

Configuration

For Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "openweathermap": {
      "command": "npx",
      "args": ["@tristau/openweathermap-mcp"],
      "env": {
        "OPENWEATHERMAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

For GitHub Copilot (VS Code)

Add the following to your MCP configuration file:

Linux: ~/.config/Code/User/mcp.json Windows: %APPDATA%\Code\User\mcp.json macOS: ~/Library/Application Support/Code/User/mcp.json

{
  "servers": {
    "openweathermap": {
      "command": "npx",
      "args": ["@tristau/openweathermap-mcp"],
      "env": {
        "OPENWEATHERMAP_API_KEY": "your_api_key_here"
      },
      "type": "stdio"
    }
  }
}

Environment Variables

Your OpenWeatherMap API key is configured through the environment variables in the MCP client configuration above.

Obtaining an API Key

1. Sign up at OpenWeatherMap
2. Subscribe to the "One Call API 3.0" plan
3. Copy your API key to the .env file

Note: The One Call API 3.0 requires a paid subscription after 1,000 free calls per day.

Usage

Once configured with your MCP client, you can ask your AI assistant:

• "What's the current weather in Paris?"
• "Show me the 5-day forecast for Tokyo"
• "What's the weather like in Herndon, Virginia?"
• "Get me weather alerts for Miami"

MCP Client Configuration (Development)

For development or local modifications, add this server to your MCP client configuration:

{
  "mcpServers": {
    "openweathermap": {
      "command": "node",
      "args": ["/path/to/openweathermap-mcp/dist/index.js"],
      "env": {
        "OPENWEATHERMAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Running the Server (Development)

Development mode:

pnpm run dev

Production mode:

pnpm run start

Example Usage

Get current weather for a city:

{
  "tool": "get_current_weather",
  "arguments": {
    "location": {
      "city": "New York",
      "state": "NY",
      "country": "US"
    },
    "units": "metric"
  }
}

Get hourly forecast by coordinates:

{
  "tool": "get_hourly_forecast",
  "arguments": {
    "location": {
      "lat": 40.7128,
      "lon": -74.0060
    },
    "hours": 24,
    "units": "imperial"
  }
}

Geocode a location:

{
  "tool": "geocode_location",
  "arguments": {
    "query": "Paris, France",
    "limit": 1
  }
}

API Reference

Location Input

All weather tools accept a flexible location object:

interface LocationInput {
  // Option 1: Coordinates (most efficient)
  lat?: number;
  lon?: number;
  
  // Option 2: Address components
  city?: string;
  state?: string;
  country?: string;
  
  // Option 3: Zip/postal code
  zipCode?: string;
  country?: string; // optional, defaults to US
}

Weather Options

Most weather tools accept these options:

interface WeatherOptions {
  units?: 'standard' | 'metric' | 'imperial'; // Default: 'metric'
  lang?: string; // Language code, default: 'en'
  exclude?: string[]; // Data parts to exclude
}

Units

• metric: Celsius, m/s, km/h
• imperial: Fahrenheit, mph
• standard: Kelvin, m/s

Languages

The API supports 40+ languages. Some examples:

• en - English (default)
• es - Spanish
• fr - French
• de - German
• ja - Japanese
• zh_cn - Chinese Simplified

Development

Local Development Setup

If you want to modify or contribute to this MCP server:

1. Clone the repository:

   git clone <repository-url>
   cd openweathermap-mcp

2. Install dependencies:

   pnpm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your OpenWeatherMap API key

4. Build the project:

   pnpm run build

Available Scripts

# Development
pnpm run dev          # Start development server with hot reload
pnpm run build        # Build TypeScript to JavaScript
pnpm run start        # Start production server

# Code Quality
pnpm run lint         # Run ESLint
pnpm run lint:fix     # Fix ESLint issues automatically
pnpm run format       # Format code with Prettier
pnpm run typecheck    # Check TypeScript types

# Testing
pnpm run test         # Run tests
pnpm run test:watch   # Run tests in watch mode

Project Structure

├── src/
│   ├── types/          # TypeScript type definitions
│   │   └── weather.ts
│   ├── services/       # API service classes
│   │   ├── geocoding.ts
│   │   └── weather.ts
│   ├── utils/          # Utility functions
│   │   └── formatters.ts
│   └── index.ts        # MCP server implementation
├── tests/              # Test files
│   ├── geocoding.test.ts
│   ├── weather.test.ts
│   └── formatters.test.ts
├── dist/               # Compiled JavaScript (generated)
└── coverage/           # Test coverage reports (generated)

Running Tests

# Run all tests
pnpm test

# Run tests with coverage report
pnpm run test:coverage

# Run specific test file
pnpm test geocoding.test.ts

# Run tests in watch mode
pnpm run test:watch

# Open coverage report in browser (after running test:coverage)
pnpm run coverage:open

Test Coverage

This project maintains high test coverage with the following thresholds:

• Statements: 80% minimum
• Branches: 80% minimum
• Functions: 80% minimum
• Lines: 80% minimum

Coverage reports are generated locally and can be viewed by:

1. Running pnpm run test:coverage
2. Opening coverage/index.html in your browser, or
3. Running pnpm run coverage:open to open automatically

Coverage is automatically checked during pre-commit hooks to ensure quality standards are maintained.

Code Style

This project uses:

• ESLint for linting
• Prettier for code formatting
• TypeScript for type checking

Code is automatically formatted on commit using git hooks.

Error Handling

The server includes comprehensive error handling:

• Invalid API Key: Returns clear error message about API key issues
• Invalid Coordinates: Validates latitude/longitude ranges
• Location Not Found: Helpful error when geocoding fails
• Network Errors: Graceful handling of API timeouts and connectivity issues
• Rate Limiting: Clear messaging about API rate limits

API Rate Limits

OpenWeatherMap API limits:

• One Call API 3.0: 1,000 free calls/day, then paid tiers
• Geocoding API: 60 calls/minute, 1,000,000 calls/month

The server handles rate limiting gracefully and provides informative error messages.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes with tests
4. Run the test suite: pnpm test
5. Run linting: pnpm run lint
6. Use semantic commits: pnpm run commit (or git cz)
7. Push to the branch: git push origin feature-name
8. Submit a pull request

Semantic Commits

This project uses Conventional Commits for semantic versioning and automated changelog generation.

Commit Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks
• ci: CI/CD changes
• perf: Performance improvements
• revert: Reverting previous commits

Examples:

# Use the interactive prompt
pnpm run commit

# Or manually
git commit -m "feat: add weather alerts functionality"
git commit -m "fix: handle missing API response data"
git commit -m "docs: update installation instructions"

Commit messages are automatically validated using commitlint and husky hooks.

Automated Releases

This project uses semantic-release for automated versioning and publishing:

🚀 How it Works:

• Commits to main branch trigger automated releases
• Version is determined by commit types:
  • fix: → patch version (0.1.0 → 0.1.1)
  • feat: → minor version (0.1.0 → 0.2.0)
  • feat!: or BREAKING CHANGE: → major version (0.1.0 → 1.0.0)

📦 What Gets Released:

• ✅ Version bumped in package.json
• ✅ CHANGELOG.md updated automatically
• ✅ GitHub release created with release notes
• ✅ Package published to npm
• ✅ Git tag created

⚙️ Setup Requirements:

1. GitHub Repository Secrets:

   • NPM_TOKEN - npm authentication token for publishing
   • GITHUB_TOKEN - automatically provided by GitHub Actions

2. Branch Protection:

   • Protect main branch
   • Require pull request reviews
   • Require status checks to pass

🔧 Manual Release (if needed):

pnpm run semantic-release

License

This project is licensed under the ISC License. See the LICENSE file for details.

Support

For issues and questions:

1. Check the OpenWeatherMap API Documentation
2. Review the test files for usage examples
3. Open an issue in this repository

Changelog

v1.0.0

• Initial release
• Full OpenWeatherMap One Call API 3.0 integration
• Geocoding support for addresses and zip codes
• Comprehensive test coverage
• TypeScript support
• MCP protocol compliance