
wg-easy
io.github.ni-c由 GitHub 账号 ni-c 发布v0.6.0更新于 Oct 24, 2026
Administer wg-easy (WireGuard Easy) v15: manage VPN clients, configs, QR codes and server status
概览
管理 wg-easy(WireGuard Easy)v15 VPN 实例:列出、创建、更新、启用、停用和删除客户端,获取配置与二维码,并查看服务器状态。
- 可以做什么
- 列出并查看 VPN 客户端及其状态和流量统计,读取服务器版本、设置与接口信息
- 创建、更新、启用和停用客户端,更新为部分合并,只改动指定的字段
- 永久删除客户端
- 获取客户端的 WireGuard 配置文件或其 SVG 二维码
- 生成有效期五分钟的一次性配置下载链接
- 可筛选加载哪些工具,或以只读模式仅注册列表与状态类工具
- 适用场景
- 当你运行 wg-easy v15 实例,希望助手代为处理日常 VPN 客户端管理——为新设备开通、发放配置或二维码、临时封禁某个客户端、查看服务器状态——而不必打开网页界面时适用。
- 运行要求
- 需要 Node.js 24 或更高版本(npm 包)或 Docker(容器镜像),以及可通过网络访问的 wg-easy v15+ 实例。必需的环境变量为 WG_EASY_URL、WG_EASY_USERNAME 和 WG_EASY_PASSWORD。所用管理员账号必须关闭两步验证,因为该 API 仅支持基本认证。
安装
在 SourceWeft 中
- 打开 控制台中的 wg-easy,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
wg-easy-mcp
[CI]
[OpenSSF Scorecard]
[Socket Badge]
[Glama score]
[npm version]
[container image]
[HTTP via mcp-hub]
[docs]
[sponsor]
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-httpURL 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 overWG_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.
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 Desktop
Add to your claude_desktop_config.json:
Codex
Add to your ~/.codex/config.toml:
From source
Docker
A multi-arch image (linux/amd64, linux/arm64) with an SBOM and build provenance is published to GitHub Container Registry:
The image talks MCP over stdio, so clients need docker run -i (no port is
exposed):
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:
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:
The untrusted marker is a field and not only a sentence in the text, because a
client that reads the structured half and ignores the text would otherwise get
free-form client names, DNS entries and endpoints with no framing at all. Every
tool carries it except delete_client, which reports an id this server was
given and nothing that came back from the instance.
Three answers changed shape to fit, and all three for the same reason: a schema
whose root is not an object is served to a 2025-era client rewritten as
{result: …}, so the tool would answer differently depending on who asked.
An oversized answer is now shortened as an object rather than cut as a
string: the longest text field is shortened first, then list entries are
dropped, and a truncated field says what was cut and how much there was. A
document sliced at a byte offset is not a smaller answer, it is an unparseable
one — and the two channels have to carry the same value.
What wg-easy sends is described with every field optional and unknown fields allowed; only what this server builds is exact. The SDK validates each result against its schema before it goes out, so a stricter shape would turn a wg-easy release that adds a field into a tool that fails outright.
Safety
- Five tools ask a person, not just the model.
create_client,update_client,enable_client,delete_clientandgenerate_one_time_linkraise a real dialog through MCP elicitation where the client supports it. Only one of the five destroys anything — the others issue a VPN credential, re-arm one, can widen a route, and mint an unauthenticated URL that hands out a private key.disable_clientis the one write tool that never asks: it can only withdraw access. Where the client cannot show a dialog they fall back to a random token valid for 5 minutes and bound to the exact target (forupdate_client, to the exact edit), which proves the call was made twice with the same arguments and nothing more.ELICITATION=falsetakes that fallback deliberately; it never removes the guard. See Asking a person. - Key material is redacted everywhere it is not the point. A field name is matched by its suffix —
password,passwd,passphrase,secret,token,apiKey,privateKey,preSharedKey, plus anything starting withtotp— sometricsPassword, which carries the argon2 hash of the metrics token, is covered along with every other<prefix>Secretwg-easy invents. (keyis not a suffix: it would takepublicKeywith it.) Values are replaced with[redacted]at every nesting level — inget_server_info's admin responses, which carry the WireGuard server key, and inlist_clientsandget_client, which carry each client's own key. Live one-time-link tokens are redacted from the same two, becauseGET /cnf/<token>serves the whole configuration with no login at all;expiresAtsurvives, so a listing still shows that a link is live.get_client_config,get_client_qrcodeandgenerate_one_time_linkare the deliberate exceptions: handing a peer its configuration is what they are for, and somebody asked. - Everything the wg-easy API returns carries an explicit untrusted-data marker and a 60 000-character budget, measured on the text that is actually emitted. Client names, DNS entries and endpoints are free-form strings, so they are marked as data to report rather than instructions to follow, control characters and BiDi overrides are stripped from them (field names included), and a single oversized field cannot flood the model's context.
- Nothing the instance sends is taken on trust. Every field an output schema types is checked at the boundary and left out when it does not hold, so one record with a string
idor a1e999cannot take a whole listing down withOutput validation error. Entries that are not client records at all are counted inskippedrather than dropped in silence. - Response bodies have a ceiling (8 MiB, refused on a declared
content-lengthbefore a byte is read) and the status is read before the body, so a401behind a large proxy page is still a401. A refused login is repeated from memory for ten seconds rather than retried. - A
WG_EASY_URLcontaining embedded credentials (user:password@host) is rejected at startup — they would otherwise be echoed in the startup log and prefixed onto every request. Only its origin and path are kept, and no startup diagnostic echoes a value back. - Upstream error bodies are labelled as untrusted, stripped of control characters and cut at 200 characters; HTML error pages (reverse proxies) are dropped before being returned to the MCP client.
- Caller input has a length: names and filters at 200 characters, addresses at 64, list parameters at 64 entries, and a client id bounded in its pattern rather than after
Number(). WG_EASY_INSECURE_TLSonly relaxes certificate validation for the wg-easy connection — it does not disable TLS verification process-wide.WG_EASY_READ_ONLY=trueregisterslist_clients,get_clientandget_server_info, and nothing else.get_client_configandget_client_qrcodeare reads and still not in that set: what they read is a client's private key in the clear, and a read-only mode that leaves key disclosure standing is not the mode its name promises.- Tools carry MCP annotations (
readOnlyHint,destructiveHint,idempotentHint) so hosts can apply appropriate permission policies. - Keep in mind that
get_client_configandget_client_qrcodereturn the client's private key, and agenerate_one_time_linkURL allows an unauthenticated config download — treat tool output as sensitive.
The full trust model is in SECURITY.md and, in prose, at wg-easy-mcp.ni-c.de/guide/security.
Not exposed, on purpose
wg-easy v15 or newer only. Older versions expose a different, session-based API that this server does not implement.
No server administration. The tools cover the client lifecycle; the instance's own configuration, its admin accounts and its host stay outside the tool list.
Safety
- Five tools ask a person first, through MCP elicitation:
create_client,update_client,enable_client,delete_clientandgenerate_one_time_link. Only one of them destroys anything — the others are on the list becausedestructiveHintis the wrong axis for what they do. A new client is a credential that reaches every network behind the VPN,update_clientcan widenserverAllowedIps, andenable_clientre-arms a key pair that is already installed on a peer. - The approval is bound to the exact edit, so approving a rename does not license a later call that widens the routes.
disable_clientdeliberately stays ungated: it only ever withdraws access, and making the safe move the slow one would be the wrong trade.- Client names, addresses and the instance's own strings are marked as untrusted data, and oversized output is truncated with the omission stated.
WG_EASY_READ_ONLY=trueregisters the read tools and nothing else.
Documentation
The full guide, tool reference and security notes live at
wg-easy-mcp.ni-c.de (source in docs/).
Development
CI runs the suite on Node 24 and 26 and adds npm audit, CodeQL and a Trivy scan of the container image on both architectures. See CONTRIBUTING.md.
The documentation site lives in docs/ with its own manifest:
Releasing
- Bump the version in
package.jsonand add aCHANGELOG.mdentry. - Commit, then tag and push:
git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z
The release workflow runs the test suite, publishes to npm (via trusted publishing, no token, with provenance), creates a GitHub release from the changelog entry and updates the entry in the official MCP Registry (io.github.ni-c/wg-easy-mcp, via GitHub OIDC). The container image is published to GHCR by the CI workflow on the same tag.
server.json lists both an npm and an OCI package; the registry job syncs the version into both before publishing. If it ever fails, fix main and re-run mcp-registry.yml via workflow_dispatch — re-running the tag job checks out the old tree.
Releasing
Releases are tag-driven. Bump package.json, move the [Unreleased] notes in
CHANGELOG.md under the new version, commit, then:
The release workflow publishes to npm via Trusted Publishing (OIDC, with provenance), pushes the multi-arch container image to GHCR, creates the GitHub release from the CHANGELOG section, and updates the entry in the official MCP registry.
Contributing
Issues, discussions and pull requests are welcome — see CONTRIBUTING.md. For vulnerabilities please use private reporting rather than a public issue; the policy is in SECURITY.md.
License
MIT © Willi Thiel
来源:README.md,提交 456990e
工具
0版本历史
1- v0.6.0最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分