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.

OS	Install
Linux	Install the Docker Engine daemon: sudo apt install docker.io (Debian/Ubuntu) or follow docs.docker.com. Add your user to the docker group: sudo usermod -aG docker $USER then log out and back in.
macOS	Install Docker Desktop for Mac. Start the app and wait for the whale icon in the menu bar.
Windows	Install Docker Desktop for Windows (requires WSL 2 or Hyper-V). Start Docker Desktop before running WEATHGARDS.

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