# mcp-cwa

[![PyPI version](https://img.shields.io/pypi/v/mcp-cwa)](https://pypi.org/project/mcp-cwa/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-cwa)](https://pypi.org/project/mcp-cwa/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub release](https://img.shields.io/github/v/release/asgard-ai-platform/mcp-cwa)](https://github.com/asgard-ai-platform/mcp-cwa/releases)
[![Publish to PyPI](https://github.com/asgard-ai-platform/mcp-cwa/actions/workflows/publish.yml/badge.svg)](https://github.com/asgard-ai-platform/mcp-cwa/actions/workflows/publish.yml)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)

MCP server for CWA (中央氣象署, Central Weather Administration) Open Data API. Provides 36 read-only tools across 7 weather data categories for AI agents such as Claude.

[繁體中文](README.zh-TW.md)

Part of the [Asgard AI Platform](https://github.com/asgard-ai-platform) open-source ecosystem.

## Features

- **36 tools** covering all major CWA Open Data categories
- **80 API endpoints** accessible via intelligent tool grouping (e.g. 44 township forecasts → 2 tools with county parameter)
- **22 county mapping** for township-level weather forecasts
- All tools are read-only with `readOnlyHint=True` annotations

## Categories

| Category | Tools | Description |
|----------|-------|-------------|
| Forecast (預報) | 9 | 36-hour, 3-day, 1-week forecasts; township forecasts; tidal; cold injury; temperature diff |
| Observation (觀測) | 7 | Weather stations, rainfall, 10-min observations, UV index, ozone, marine |
| Earthquake (地震海嘯) | 5 | Tsunami info, significant/local earthquake reports (zh/en) |
| Climate (氣候) | 5 | 30-day observations, daily rainfall, monthly average, station info |
| Warning (天氣警特報) | 7 | Weather warnings by county, heavy rain, cold, heat, typhoon, tropical cyclone |
| Numerical (數值預報) | 1 | Heat injury index |
| Astronomy (天文) | 2 | Sunrise/sunset, moonrise/moonset |

## Quick Start

### Install from PyPI

```bash
pip install mcp-cwa
```

### Or clone and install locally

```bash
git clone https://github.com/asgard-ai-platform/mcp-cwa.git
cd mcp-cwa
uv venv && source .venv/bin/activate
uv pip install -e .
```

### Claude Desktop / Claude Code

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "mcp-cwa": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/mcp-cwa",
      "env": {
        "CWA_API_KEY": "CWA-your-authorization-code"
      }
    }
  }
}
```

### Get API Key

1. Register at [CWA Open Data Platform](https://opendata.cwa.gov.tw/)
2. After registration, obtain your authorization code from the member page

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CWA_API_KEY` | Yes | CWA Open Data API authorization code |

## Example Usage

```
User: 臺北市現在天氣如何？
Agent: [calls get_weather_observation(county_name="臺北市")]

User: 最近有地震嗎？
Agent: [calls get_significant_earthquake(limit=3)]

User: 明天高雄日出時間？
Agent: [calls get_sunrise_sunset(county_name="高雄市", date="2025-04-16")]
```

## Development

```bash
# Install dependencies
uv venv && source .venv/bin/activate
uv pip install -e .

# Run E2E tests (requires real API key)
CWA_API_KEY=CWA-xxx python3 tests/test_all_tools.py
```

## API Reference

All tools query the CWA Open Data API at `https://opendata.cwa.gov.tw/api/v1/rest/datastore/{dataset_id}`.

See [_spec/api-tools-list.md](_spec/api-tools-list.md) for the complete endpoint inventory.

## License

MIT — see [LICENSE](LICENSE)