wg-easy

wg-easy-mcp

A Model Context Protocol (MCP) server for administering wg-easy (WireGuard Easy) instances.

Lets MCP clients like Claude Code, Claude Desktop or Codex manage your WireGuard VPN: list, create, update, enable/disable and delete clients, fetch configuration files and QR codes, and inspect the server status — all through the wg-easy v15 REST API.

Eleven tools is the ceiling, not the floor: WG_EASY_ALLOW_TOOLS=essential registers a curated six instead, and a model picks the right tool far more reliably from six than from eleven — see choosing which tools load.

What makes it different

The full client lifecycle over the wg-easy v15 REST API, including .conf files, QR codes and one-time download links.

Partial updates merge. An update reads the current client state and changes only the fields you named, instead of overwriting the rest with defaults.

`disable_client` stays ungated on purpose. Every other write asks a person first through MCP elicitation; that one only ever withdraws access, and making it harder would be making the safe move the slow one.

Requirements

• Node.js ≥ 24
• A running wg-easy v15+ instance
• 2FA (TOTP) must be disabled for the account used by this server — the wg-easy API only supports Basic Authentication and does not work with 2FA enabled

Note: The wg-easy REST API is not yet declared stable and may change between releases. This server targets wg-easy v15.

Configuration

Configuration is provided via environment variables:

Use `https://`. With a plain-http URL the Basic Auth credentials and all

WireGuard private keys travel unencrypted; the server prints a warning unless

the host is local. For self-signed certificates prefer a proper internal CA

over WG_EASY_INSECURE_TLS.

Without credentials the server still starts and lists its tools (so registries and inspectors can introspect it), but every tool call fails with setup instructions instead of reaching the wg-easy API.

Choosing which tools load

WG_EASY_ALLOW_TOOLS and WG_EASY_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of six: get_server_info, list_clients, get_client, create_client, enable_client, disable_client.

get_client_config, get_client_qrcode and generate_one_time_link are not in it, and neither is delete_client: all four either destroy something irreversibly or hand out a peer's private key. Name them where you want them.

WG_EASY_ALLOW_TOOLS=essential

WG_EASY_ALLOW_TOOLS=essential,get_client_config WG_EASY_ALLOW_TOOLS=list_clients,get_client_config WG_EASY_DENY_TOOLS=delete_client,create_client

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under WG_EASY_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add wg-easy -s user \

-e WG_EASY_URL=https://vpn.example.com:51821 \ -e WG_EASY_USERNAME=admin \ -e WG_EASY_PASSWORD=your-password \ -- npx -y wg-easy-mcp

Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "wg-easy": { "command": "npx", "args": ["-y", "wg-easy-mcp"], "env": { "WG_EASY_URL": "https://vpn.example.com:51821", "WG_EASY_USERNAME": "admin", "WG_EASY_PASSWORD": "your-password" } } } }

Codex

Add to your ~/.codex/config.toml:

[mcp_servers.wg-easy]

command = "npx" args = ["-y", "wg-easy-mcp"] env = { WG_EASY_URL = "https://vpn.example.com:51821", WG_EASY_USERNAME = "admin", WG_EASY_PASSWORD = "your-password" }

From source

git clone https://github.com/ni-c/wg-easy-mcp.git

cd wg-easy-mcp npm install npm run build

then use node /path/to/wg-easy-mcp/dist/index.js as the command

Docker

A multi-arch image (linux/amd64, linux/arm64) with an SBOM and build provenance is published to GitHub Container Registry:

docker run -i --rm \

-e WG_EASY_URL=https://vpn.example.com:51821 \ -e WG_EASY_USERNAME=admin \ -e WG_EASY_PASSWORD=your-password \ ghcr.io/ni-c/wg-easy-mcp:latest

The image talks MCP over stdio, so clients need docker run -i (no port is exposed):

{

"mcpServers": { "wg-easy": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "WG_EASY_URL", "-e", "WG_EASY_USERNAME", "-e", "WG_EASY_PASSWORD", "ghcr.io/ni-c/wg-easy-mcp:latest" ], "env": { "WG_EASY_URL": "https://vpn.example.com:51821", "WG_EASY_USERNAME": "admin", "WG_EASY_PASSWORD": "your-password" } } } }

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches wg-easy-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{

"mcpServers": { "wg-easy": { "command": "npx", "args": ["-y", "wg-easy-mcp"], "env": { "WG_EASY_ALLOW_TOOLS": "essential" }, "denyTools": ["delete_client"] } } }

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

👤 asks a person through MCP elicitation · falls back to a two-call confirm_token where the client cannot show a dialog.

Structured output

Every tool declares an outputSchema and answers with structuredContent alongside the text block, so a client can use the result without parsing prose:

{

"untrusted": true, "source": "wg-easy", "count": 2, "clients": [{ "id": 1, "name": "laptop", "enabled": true }], }

The untrusted marker is a field and not only a sentence in the text, because a client that reads th