Weather MCP

A simple and easy-to-use weather query MCP tool, supporting both CLI and MCP Server usage modes.

Features

• 🌤️ Real-time Weather Query - Get current weather for any city worldwide

• 🔧 CLI Support - Query weather directly from the command line

• 🤖 MCP Protocol - Supports AI clients like Claude and Cursor

• 🌍 Global Coverage - Supports city names in multiple languages including Chinese and English

• ⚡ Free API - Uses the free Open-Meteo weather service, no API Key required

• 📝 Type Safe - Full TypeScript + Zod type support

Related MCP server: Weather MCP Server

Installation

Method 1: Global npm installation (Recommended)

npm install -g weather-mcp

Method 2: Use directly with npx

npx weather-mcp weather 北京

Method 3: Source installation

git clone https://github.com/tengzhijian/weather-mcp.git
cd weather-mcp
npm install
npm run build

CLI Usage

# 查询天气
weather-mcp weather 北京
weather-mcp weather Shanghai

# 查看帮助
weather-mcp --help
weather-mcp --version

Example Output

{
  "ok": true,
  "data": {
    "city": "北京 (中国)",
    "temperature": 22,
    "humidity": 70,
    "description": "多云",
    "windSpeed": 9.3,
    "updatedAt": "2024-01-15T08:30:00.000Z"
  }
}

MCP Server Configuration

Claude Desktop

Edit %APPDATA%/Claude/settings.json (Windows) or ~/Library/Application Support/Claude/settings.json (Mac):

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

Cursor

Add in Cursor Settings → MCP:

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

Local Development Version

If you are running from source:

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

Available Tools

getWeather

Query weather information for a specified city.

Parameters:

• city (string, required): City name, e.g., Beijing, Shanghai, Guangzhou, London, Tokyo

Returns:

• city: City name (including country)

• temperature: Temperature (Celsius)

• humidity: Humidity (percentage)

• description: Weather description (sunny, cloudy, etc.)

• windSpeed: Wind speed (km/h)

• updatedAt: Data update time

listSupportedCities

Get a list of example cities supported for queries.

Returns:

• cities: List of common city examples

• note: Note (actually supports any city worldwide)

AI Client Usage Examples

After configuration, you can ask directly in clients like Claude or Cursor:

"What is the weather in Beijing today?" "Will it rain in Shanghai tomorrow?" "Check the weather in New York"

The AI will automatically call the getWeather tool to retrieve weather information.

Development

# 安装依赖
npm install

# 开发模式
npm run dev weather 北京

# 运行测试
npm test

# 类型检查
npm run typecheck

# 构建
npm run build

Tech Stack

• TypeScript - Type-safe JavaScript

• MCP SDK - Model Context Protocol

• Commander.js - CLI framework

• Zod - Schema validation

• Vitest - Testing framework

• Open-Meteo - Free weather API

Project Structure

weather-mcp/
├── src/
│   ├── index.ts           # 入口文件
│   ├── cli.ts             # CLI 命令
│   ├── mcp-server.ts      # MCP Server
│   ├── weather-gateway.ts # 天气 API 封装
│   └── version.ts         # 版本号
├── tests/                 # 测试文件
├── .github/workflows/     # GitHub Actions
├── package.json
├── tsconfig.json
└── README.md

CI/CD

The project uses GitHub Actions for automation:

• CI: Automatically runs tests on every PR and Push (Node.js 18/20/22)

• Release: Manually triggered release to npm

License

MIT

Acknowledgments

• Weather data provided by Open-Meteo free API

• Follows the Model Context Protocol specification