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

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

Geocoding Tools

geocode_location - Convert location names to coordinates
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", "--apikey", "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", "--apikey", "your_api_key_here"],
      "type": "stdio"
    }
  }
}

API Key Configuration

Your OpenWeatherMap API key is configured through the --apikey argument in the MCP client configuration above.

Obtaining an API Key

Sign up at OpenWeatherMap
Subscribe to the "One Call API 3.0" plan
Use your API key in the --apikey argument when configuring the MCP server

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", "--apikey", "your_api_key_here"]
    }
  }
}

Running the Server

For end users (recommended):

npx @tristau/openweathermap-mcp --apikey YOUR_API_KEY

For development/local modifications:

# Development mode (with hot reload)
pnpm run dev

# Local production build
node dist/index.js --apikey YOUR_API_KEY

# Testing the server
node test-server.js

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:

Clone the repository:

git clone <repository-url>
cd openweathermap-mcp

Install dependencies:
```
pnpm install
```
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:

Running pnpm run test:coverage
Opening coverage/index.html in your browser, or
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

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes with tests
Run the test suite: pnpm test
Run linting: pnpm run lint
Use semantic commits: pnpm run commit (or git cz)
Push to the branch: git push origin feature-name
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:

GitHub Repository Secrets:
- NPM_TOKEN - npm authentication token for publishing
- GITHUB_TOKEN - automatically provided by GitHub Actions
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:

Check the OpenWeatherMap API Documentation
Review the test files for usage examples
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