# OpenWeatherMap MCP Server
[](https://badge.fury.io/js/%40tristau%2Fopenweathermap-mcp)
[](https://opensource.org/licenses/MIT)
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:
```bash
npx @tristau/openweathermap-mcp
```
For development or local modifications, see the [Development](#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`
```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`
```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
1. Sign up at [OpenWeatherMap](https://openweathermap.org/api)
2. Subscribe to the "One Call API 3.0" plan
3. 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:
```json
{
"mcpServers": {
"openweathermap": {
"command": "node",
"args": ["/path/to/openweathermap-mcp/dist/index.js", "--apikey", "your_api_key_here"]
}
}
}
```
### Running the Server
**For end users (recommended):**
```bash
npx @tristau/openweathermap-mcp --apikey YOUR_API_KEY
```
**For development/local modifications:**
```bash
# 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:**
```json
{
"tool": "get_current_weather",
"arguments": {
"location": {
"city": "New York",
"state": "NY",
"country": "US"
},
"units": "metric"
}
}
```
**Get hourly forecast by coordinates:**
```json
{
"tool": "get_hourly_forecast",
"arguments": {
"location": {
"lat": 40.7128,
"lon": -74.0060
},
"hours": 24,
"units": "imperial"
}
}
```
**Geocode a location:**
```json
{
"tool": "geocode_location",
"arguments": {
"query": "Paris, France",
"limit": 1
}
}
```
## API Reference
### Location Input
All weather tools accept a flexible `location` object:
```typescript
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:
```typescript
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:**
```bash
git clone <repository-url>
cd openweathermap-mcp
```
2. **Install dependencies:**
```bash
pnpm install
```
3. **Build the project:**
```bash
pnpm run build
```
### Available Scripts
```bash
# 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
```bash
# 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](https://conventionalcommits.org/) 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:**
```bash
# 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):**
```bash
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](https://openweathermap.org/api)
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
