docker-mcp-weather

A Model Context Protocol (MCP) server that exposes real-time weather data to any MCP-compatible client.

• No API key required — powered by the free Open-Meteo weather and geocoding APIs
• Ships as a multi-arch Docker image (linux/amd64, linux/arm64) on GHCR
• Stateless HTTP transport — plain JSON over POST /mcp, no SSE streaming required

---

Tools

Tool	Description	Returns
get_current_weather	Current conditions for any city	Temperature (°C/°F), feels-like, humidity, wind speed, and conditions
get_forecast	24-hour hourly forecast	Temperature (°C/°F), precipitation probability, and conditions per hour

Both tools accept:

Parameter	Type	Required	Description
city	string	Yes	City name (e.g., "London", "Tokyo")
region	string	No	State or region for disambiguation (e.g., "Georgia")
country_code	string	No	ISO 3166-1 alpha-2 country code (e.g., "US", "FR")

Every response includes the fully resolved location (City, Region, Country, Postcode) so disambiguation errors are immediately visible.

---

Quick Start

Docker (pre-built image)

docker pull ghcr.io/nmarus/docker-mcp-weather:latest
docker run -d -p 8000:8000 ghcr.io/nmarus/docker-mcp-weather:latest

Docker (build locally)

docker build -t mcp-weather .
docker run -d -p 8000:8000 mcp-weather

Local development

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

The MCP endpoint is available at http://localhost:8000/mcp in all cases.

---

MCP Client Configuration

Add the following to your MCP client's server configuration:

{
  "mcpServers": {
    "weather": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

---

API Reference

Endpoints

Method	Path	Description
POST	/mcp	MCP JSON-RPC 2.0 endpoint
GET	/health	Health check — returns {"status": "ok"}

Required headers for /mcp

Content-Type: application/json
Accept: application/json, text/event-stream

Example request

curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_current_weather",
      "arguments": {"city": "London"}
    }
  }'

---

Configuration

Variable	Default	Description
PORT	8000	TCP port the server listens on

Pass environment variables at container runtime:

docker run -d -p 9000:9000 -e PORT=9000 ghcr.io/nmarus/docker-mcp-weather:latest

Note: The Docker HEALTHCHECK hardcodes port 8000. Changing PORT does not update the health probe.

---

Development

Testing

pip install -r requirements.txt -r requirements-dev.txt

pytest src/tests/               # all tests
pytest -m unit                  # unit tests only (no network required)
pytest -m integration           # integration tests only (requires internet)
pytest -m unit --cov=src --cov-report=term-missing  # unit tests with coverage

Linting

pip install -r requirements-dev.txt

ruff check src/          # check for lint errors
ruff format --check src/ # check formatting without modifying
ruff check --fix src/    # auto-fix fixable issues

Security scanning

bandit -r src/ -c pyproject.toml  # static analysis (SAST)
safety check -r requirements.txt  # dependency vulnerability check

Pre-commit hooks

pip install pre-commit
pre-commit install           # install hooks into .git/hooks
pre-commit run --all-files   # run manually

---

License

The MIT License (MIT)

Copyright 2026 Nick Marus (nmarus@gmail.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.