mirror-earth-mcp 0.2.0

Model Context Protocol server for Mirror Earth weather data.

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
• 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:

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

{
  "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:

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

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:

uv publish