bridgemcp-server-weather

The official BridgeMCP reference server — weather data via Open-Meteo.

No API key required.

This server demonstrates the recommended architecture for production-quality BridgeMCP servers. It is the first official server in the BridgeMCP ecosystem and is intended as a reference for all future official servers.

---

Tools

Tool	Description
get_current_weather	Current temperature, humidity, wind, precipitation, and conditions
get_forecast	Multi-day forecast (1–16 days) with highs/lows, precipitation, and sunrise/sunset
get_weather_summary	Plain-language summary optimized for AI context windows

All tools accept:

• City name: "London"
• City + country: "Paris, France"
• Coordinates: "51.5074,-0.1278"

---

Installation

pip install bridgemcp-server-weather

For running as an MCP server (required for bridgemcp-weather CLI):

pip install 'bridgemcp-server-weather[mcp]'

---

Usage

As an MCP server (stdio — for Claude Desktop, Cursor, etc.)

bridgemcp-weather

As an MCP server (HTTP/SSE — for network clients)

bridgemcp-weather --http
bridgemcp-weather --http --host 0.0.0.0 --port 9000

Programmatic use

from bridgemcp_weather import create_app

app = create_app()

# Call tools directly (useful in tests and scripts)
result = await app.acall("get_current_weather", location="Tokyo")
print(result["temperature_c"])  # 22.5

# Run as MCP server
app.run()

Claude Desktop configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "bridgemcp-weather"
    }
  }
}

---

Architecture

This server is the reference implementation for BridgeMCP server architecture.

bridgemcp_weather/
├── __init__.py       # Public API: create_app, WeatherPlugin
├── _version.py       # Single version source of truth
├── server.py         # BridgeMCP app + WeatherPlugin + CLI entry point
├── client.py         # Pure async HTTP layer (no BridgeMCP types)
├── geocoding.py      # Open-Meteo geocoding (city name → lat/lon)
├── models.py         # Pydantic models + WMO code descriptions
└── exceptions.py     # WeatherError, WeatherAPIError, GeocodingError

Key design decisions

WeatherPlugin owns the httpx client lifecycle. The httpx.AsyncClient is opened in on_startup and closed in on_shutdown. This is the correct BridgeMCP pattern for any plugin that owns async resources. The client is never a module-level global.

Tools are registered in WeatherPlugin.setup() (synchronously). The BridgeMCP adapter builds the MCP server before startup hooks run. All tools must be registered before app.run() is called. setup() is the correct place.

The HTTP layer contains no BridgeMCP types. client.py and geocoding.py accept an httpx.AsyncClient and raise WeatherError subclasses. They know nothing about BridgeMCP, InvocationContext, or MCP protocol types. This makes the HTTP layer independently testable and reusable.

Tools return dict from model.model_dump(). Tools never return JSON strings. Pydantic models are dumped to dicts at the tool boundary, preserving type information for BridgeMCP's schema generation.

---

Development

git clone https://github.com/Arsie-codes/bridgemcp-server-weather
cd bridgemcp-server-weather
pip install -e '.[dev]'

# Run tests
pytest tests/ -v

# Lint and format
ruff check bridgemcp_weather tests
black bridgemcp_weather tests
pyright bridgemcp_weather

---

Ecosystem

Package	Description
bridgemcp-py	The BridgeMCP framework
bridgemcp-logging	Official logging plugin
bridgemcp-server-weather	This package — official weather reference server

---

License

MIT — see LICENSE.