WEATHGARDS

Local cross-OS MCP gateway for Docker containers, processes and services.

WEATHGARDS scans your machine for running Docker containers, OS processes, and system services, then exposes pre-written MCP tools over a secure local network endpoint so a remote LLM (Claude, GPT-4, etc.) can interrogate your environment in real time — without generating any code at runtime.

Prerequisites

Docker (optional but recommended)

WEATHGARDS works without Docker; container scanning is simply disabled when the daemon is unreachable.

Python 3.12+

# Linux / macOS
python3 --version   # must be ≥ 3.12

# Windows (PowerShell)
python --version

Install uv — the package manager used throughout:

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation

# 1. Clone
git clone https://github.com/your-org/weathgards.git
cd weathgards

# 2. Install Python dependencies
uv sync

# 3. Configure environment
cp .env.example .env          # Linux / macOS
copy .env.example .env        # Windows (cmd)
# Edit .env — at minimum set WEATHGARDS_MCP_TOKEN

# 4. Build the frontend (one-time, requires Node 18+)
cd frontend && npm install && npm run build && cd ..

# 5. Start WEATHGARDS
uv run weathgards

Open http://127.0.0.1:8765 in your browser.

Per-OS Quick Reference

Linux

uv sync
cp .env.example .env
# nano .env  →  set WEATHGARDS_MCP_TOKEN
uv run weathgards

Docker socket at /var/run/docker.sock. If missing, container scanning is skipped automatically.

macOS

uv sync
cp .env.example .env
# open -e .env  →  set WEATHGARDS_MCP_TOKEN
uv run weathgards

Docker Desktop must be running before WEATHGARDS starts. The socket is detected automatically under both /var/run/docker.sock and the Docker Desktop path.

Windows (PowerShell)

uv sync
Copy-Item .env.example .env
# notepad .env  →  set WEATHGARDS_MCP_TOKEN
uv run weathgards

Docker Desktop must be running. The named pipe \\.\pipe\docker_engine is checked automatically. No administrator privileges required.

Connect a Remote LLM

Once WEATHGARDS is running with network exposure enabled, your LLM client needs three pieces of information: the endpoint URL, the Bearer token, and the MCP client config snippet.

Step 1 — Enable network exposure

In the Serveur tab of the cockpit UI:

1. Toggle "Exposer sur le réseau local"

2. Click "Démarrer le serveur MCP"

Or configure it persistently in .env before starting:

WEATHGARDS_MCP_TOKEN=your-secret-token-here
WEATHGARDS_HOST=0.0.0.0

Step 2 — Retrieve the endpoint and token

The Informations de connexion section shows the live values:

Endpoint MCP : http://192.168.1.42:9766/mcp
Token        : wg-xxxxxxxxxxxxxxxxxxxx

Step 3 — Configure your MCP client

Paste the generated JSON snippet (available via the "Copier" button) into your Claude Desktop / MCP client config:

{
  "mcpServers": {
    "weathgards": {
      "url": "http://192.168.1.42:9766/mcp",
      "headers": {
        "Authorization": "Bearer wg-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Desktop config path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

⚠ Security Warning

Network exposure requires authentication — no exceptions.

Binding the MCP server to 0.0.0.0 makes it reachable by every device on your LAN. WEATHGARDS enforces a Bearer token on every /mcp request and refuses to start in network mode without a configured token.

Recommended hardening:

• Set WEATHGARDS_MCP_TOKEN to a long random string (≥ 32 characters):

  python3 -c "import secrets; print('wg-' + secrets.token_hex(32))"

• Restrict access to a specific subnet via WEATHGARDS_ALLOWED_CLIENTS=192.168.1.0/24 in .env.

• Never commit your .env file — it is already in .gitignore.

• Do not expose WEATHGARDS on a public network. It is designed for a trusted local subnet only.

Development

# Install with dev extras
uv sync --extra dev

# Run with auto-reload
uv run weathgards --reload

# Lint
uv run ruff check src tests

# Format
uv run ruff format src tests

# Type check
uv run mypy src

# Tests (with coverage)
uv run pytest

# Tests — fast, no coverage
uv run pytest --no-cov

# Smoke tests only
uv run pytest tests/test_smoke.py --no-cov -v

# Build frontend
cd frontend && npm run build