Metadata-Version: 2.4
Name: mirror-earth-mcp
Version: 0.2.0
Summary: Model Context Protocol server for Mirror Earth weather data.
Project-URL: Homepage, https://gitee.com/gfyml/mirror-earth-mcp
Project-URL: Repository, https://gitee.com/gfyml/mirror-earth-mcp.git
Author: Mirror Earth
License: MIT
Keywords: mcp,mirror-earth,weather
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Mirror Earth MCP

`mirror-earth-mcp` is a Python implementation of a Model Context Protocol (MCP) server for Mirror Earth weather data. It provides weather queries, model and variable catalogs, geocoding, local Markdown references, and batch-export task management.

## Requirements

- Python 3.9 or newer
- [uv](https://docs.astral.sh/uv/)
- A Mirror Earth API key for authenticated weather and batch-export tools

`geocode` and `reverse_geocode` use the public geocoding endpoint and do not require an API key.

## Install and Run

Run the published package directly with `uvx`:

```powershell
uvx --from mirror-earth-mcp mirror-earth-mcp
```

Set `MIRROR_EARTH_API_KEY` in the MCP client's environment. The server uses stdio transport and writes JSON-RPC responses only to standard output.

## MCP Configuration

```json
{
  "mcpServers": {
    "mirror-earth": {
      "command": "uvx",
      "args": ["--from", "mirror-earth-mcp", "mirror-earth-mcp"],
      "env": {
        "MIRROR_EARTH_API_KEY": "YOUR_MIRROR_EARTH_API_KEY"
      }
    }
  }
}
```

For Codex CLI:

```powershell
codex mcp add mirror-earth --env MIRROR_EARTH_API_KEY=YOUR_MIRROR_EARTH_API_KEY -- uvx --from mirror-earth-mcp mirror-earth-mcp
```

## Tools

| Tool | Purpose |
| --- | --- |
| `list_models` | List forecast, historical, and archive forecast models. |
| `get_model_details` | Inspect model metadata, variables, and pressure levels. |
| `list_variables` | List hourly, daily, or monthly variables. |
| `get_forecast` | Query weather forecasts by coordinates. |
| `get_historical_weather` | Query ERA5 historical weather data. |
| `get_archive_forecast` | Query a past model forecast run. |
| `get_seamless_weather` | Query continuous ERA5 and ECMWF data. |
| `geocode` / `reverse_geocode` | Resolve place names and coordinates. |
| `get_batch_usage` | Inspect batch-export quota and usage. |
| `estimate_batch_export` / `create_batch_export` | Estimate and create batch exports. |
| `get_batch_task` / `list_batch_tasks` / `cancel_batch_task` | Manage batch-export tasks. |

The server also exposes bundled API and model documentation as `mirror-earth://references/...` MCP resources.

## Development

```powershell
uv sync
uv run pytest
uv build
```

Build artifacts are written to `dist/`. To publish a new version, authenticate with a PyPI token using the `UV_PUBLISH_TOKEN` environment variable and run:

```powershell
uv publish
```
