Mcp Server For 3x Ui

3x-ui MCP 服务

适用于 3x-ui 的 MCP（模型上下文协议）服务——这是一个 Xray/V2Ray 代理管理面板。它将 3x-ui HTTP API 暴露为 MCP 工具，让大模型能够管理入站、客户端、路由规则、Xray 服务和服务器设置。

目录

• 功能
• 快速开始
• 提示词示例
• Agent 技能
• 配置
• 面板版本
• MCP 工具
• 资源
• 架构
• 开发
• 贡献
• 许可证

功能

• 完整的面板 API — 提供 169 个工具，涵盖入站、客户端、群组、主机、节点、路由、负载均衡器、地理数据、指标、令牌和维护。包含 3x-ui 暴露的所有功能，但不包括四个文件传输和节点同步路由（3x-ui v3.3.0+；参见面板版本）。
• 两种认证模式 — 支持使用 CSRF 的会话登录，或 Bearer API 令牌（XUI_API_TOKEN）；任一认证过期时，都会自动重新认证并刷新 CSRF。
• 以电子邮件为键的客户端 — 一个客户端可以关联多个入站；支持批量创建、调整、启用和删除，以及对大型面板进行服务端分页。
• 带注释的工具 — 每个工具都会声明其影响，因此 MCP 客户端可以在执行前判断调用是只读操作还是破坏性操作。
• 默认延迟加载 — 对于较大的负载，先返回摘要和 resource_link，只有在实际需要文档时才获取。
• 控制上下文预算 — XUI_TOOLSETS 仅加载指定的工具组，减少每个会话中工具架构占用的内容。
• 内置 Agent 技能 — 包含七个用于实际任务的操作流程，并已根据 Xray-core 和 3x-ui 源码验证（参见 Agent 技能）。
• Stdio 传输，除 MCP SDK 外无外部依赖。

重要

这些工具会操作正在运行的代理面板。标记为破坏性的工具会删除 客户端、将流量计数器清零，或重启 Xray 并断开所有连接—— 其中一些操作会影响整个面板，且无法撤销。请为 Agent 提供权限范围符合 其访问需求的 API 令牌，并在批量操作前备份。

快速开始

npx 只需要 Node 16+——该软件包已附带适用于 x64 和 arm64 架构的 Linux、macOS 和 Windows 预构建二进制文件，因此无需编译，也不需要 Go 工具链。若已安装 Go， go run …@latest 也同样可用；参见其他运行方式。

Claude Code

claude mcp add 3x-ui \
  --env XUI_HOST=http://localhost:2053 \
  --env XUI_USERNAME=admin \
  --env XUI_PASSWORD=your-password \
  -- npx -y @pyworkload/3x-ui-mcp

Claude Desktop / Cursor

添加到 claude_desktop_config.json（Claude Desktop）或 .cursor/mcp.json（Cursor）：

{
  "mcpServers": {
    "3x-ui": {
      "command": "npx",
      "args": ["-y", "@pyworkload/3x-ui-mcp"],
      "env": {
        "XUI_HOST": "http://localhost:2053",
        "XUI_USERNAME": "admin",
        "XUI_PASSWORD": "your-password"
      }
    }
  }
}

VS Code

添加到 .vscode/mcp.json：

{
  "servers": {
    "3x-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pyworkload/3x-ui-mcp"],
      "env": {
        "XUI_HOST": "http://localhost:2053",
        "XUI_USERNAME": "admin",
        "XUI_PASSWORD": "your-password"
      }
    }
  }
}

其他运行方式

在上述任一配置中替换 command 和 args：

方式	command	args
Go 工具链	go	["run", "github.com/pyworkload/3x-ui-mcp/cmd/xui-mcp@latest"]
预构建二进制文件	/path/to/xui-mcp	—
全局安装	xui-mcp	—

go run …@latest 会在首次使用时编译，之后则从缓存运行。 如果不想每次都使用 npx，可以通过 npm install -g @pyworkload/3x-ui-mcp 将 xui-mcp 安装到 PATH 中。

示例提示词

连接后，可以向 Agent 提出以下问题：

• "在入站 3 上创建 20 个试用客户端，流量为 10 GB，有效期为 7 天，并提供它们的订阅链接。"
• "哪些客户端的流量已用到 90% 以上？将它们的有效期全部延长 30 天，并增加 50 GB 流量。"
• "扫描 104.16.0.0/24，查找可用的 REALITY 目标，并将速度最快的一个设置到我的 VLESS 入站上。"
• "注册一个 Warp 账号，并通过它路由 *.netflix.com。"
• "没人能连接——检查 Xray 日志、面板日志，以及每个客户端上次在线的时间。"
• "现在有最多在线客户端的节点是哪个？它的负载有多高？"
• "将数据库备份到 Telegram，然后在每个节点上运行面板自更新。"

Agent 技能

skills/ 中包含七个针对面板常见操作的流程——它们涵盖了工具架构无法表达的操作知识：操作顺序，以及面板不会提醒你的事项。

技能	涵盖内容
reality-inbound	选择并验证 REALITY 伪装目标、密钥、shortId，以及修复失效的入站
diagnose-connectivity	客户端无法连接的原因，按排查成本从低到高排列，并将核心错误字符串对应到原因
panel-hardening	使用范围受限的令牌而非管理员密码、轮换、fail2ban、证书固定、备份
cdn-fallback	CDN 后的 WebSocket/gRPC/xhttp，以及通过 fallback 共享端口 443
client-lifecycle	客户端上线、订阅链接、批量续期、报告、清理
smart-routing	按域名和地理位置令牌进行分流、提供商出站，以及使用 test_route 验证规则
multi-node	添加节点、TLS 信任模式和 mTLS、选择性同步、集群监控

cp -r skills/* ~/.claude/skills/     # Claude Code, everywhere
cp -r skills/* .claude/skills/       # this project only

配置

变量	必填	说明	示例
XUI_HOST	是	面板 URL	http://localhost:2053
XUI_USERNAME	是¹	管理员用户名	admin
XUI_PASSWORD	是¹	管理员密码	admin
XUI_API_TOKEN	否	Bearer API 令牌。绕过 /panel/api/* 的 CSRF 检查	eyJ…
XUI_TOOLSETS	否	要公开的工具组（默认：全部）	clients,metrics
XUI_BASE_PATH	否	面板基础路径（默认：/）	/xui/
XUI_LOG_LEVEL	否	日志级别（默认：info）	debug、info、warn、error

¹ 请提供 XUI_USERNAME+XUI_PASSWORD 或 XUI_API_TOKEN。

认证模式（3x-ui 通过 CSRF 保护面板，并支持 API 令牌）：

• 会话 + CSRF（用户名/密码）：适用于所有工具。客户端登录后会跟踪会话 CSRF 令牌，并在写入请求中重新发送该令牌；令牌过期时会自动刷新。

• Bearer API 令牌（XUI_API_TOKEN）：每次请求都会发送令牌；对于 /panel/api/* 路由，面板无需 CSRF 验证即可接受该令牌。v3.3.0+ 中，这涵盖了此处的所有工具，包括设置和 Xray 模板。 在面板的 设置 → 安全 → API 令牌 中创建令牌。

  自 v3.7.0 起，令牌具有范围限制，也可以设置有效期，因此请为此服务指定 admin 范围。另两个范围不适用：monitor 是状态和指标路由的精简许可列表（此处的工具中只有 server_status 和 get_xray_versions 属于该范围），而 node-sync 是面板到节点流量的固定许可列表。明文令牌只会在创建时显示一次——面板会保存 SHA-256 哈希。另请注意，现在通过命令行运行 x-ui setting -getApiToken 会轮换一个共享的 cli-fallback 令牌，而不是创建新令牌；因此再次运行会使之前发放的令牌失效。

  自 v3.8.0 起，面板拒绝令牌时会返回 401，而不再像以前那样被伪装成 404。面板之后仍会检查会话，因此如果也配置了凭据，客户端会登录并重试，同时记录警告，说明令牌遭到拒绝；如果只配置了令牌，调用会失败，并显示指出该令牌的错误。错误的 XUI_BASE_PATH 仍会返回 404，因此现在可以区分这两种情况。

**缩小工具集：**每个会话中，全部 169 个工具架构合计约占用 29k 个模型上下文令牌，因此值得缩小范围。XUI_TOOLSETS 只加载所需的组：inbounds、clients、server、xray、metrics、groups、geodata、hosts、nodes、tokens、providers、maintenance 或 all。XUI_TOOLSETS=clients,metrics 会保留 47 个工具，约占 7.5k 个令牌。未知名称会导致启动失败，而不会静默地什么都不加载。

面板版本

要求 3x-ui v3.3.0 或更高版本。该版本将设置和 Xray 端点从 /panel/setting/* 和 /panel/xray/* 移至 /panel/api/ 下（上游 c6f15cd5，这是已记录的破坏性变更），此服务面向当前布局。

在较旧的面板上，入站、客户端和服务器工具仍可使用，但任何涉及设置或 Xray 模板的操作都会返回 HTTP 404。对于 v3.2.8 及更早版本的面板，请改用版本 v0.2.0。

部分工具封装的端点是在 v3.3.0 之后加入的；低于所列版本时，这些端点会返回 404：

工具	要求版本
get_balancers、set_balancer_override、test_route	v3.3.1
scan_reality_target、scan_reality_targets、get_all_inbound_links	v3.4.2
可观测性、客户端组、批量客户端状态、入站映射和回退	v3.5.0
主机组、API 令牌、客户端导出/导入、外部链接、Warp 和 NordVPN	v3.5.0
多节点工具	v3.5.0
维护、证书辅助工具、集群客户端视图、test_outbounds	v3.5.0
地理数据、HWID 设备、get_clients_by_telegram_id、set_inbound_sub_sort_index	v3.7.0
订阅负载均衡器、PIA、reload_node_mtls_client，以及令牌的 scope/expires_at	v3.7.0
validate_regex、get_factory_defaults、get_panel_update_status、get_amneziawg_logs	v3.7.0
preview_client_renewal、客户端参数 reset_weekday	v3.9.0
manage_warp 的 regMasque 操作、MASQUE 入站	v3.10.0

最后两行的范围由面板自身生成的 openapi.json 限定，该文件从 v3.5.0 才开始提供——其中某些路由可能早于此版本。

v3.8 没有新增路由。 其差异在于 JSON 结构。从 v3.3.1 开始，面板会将入站的 settings、streamSettings 和 sniffing 作为嵌套对象输出，而不是像较早版本那样发送 JSON 编码的字符串；并且每个版本都会继续为入站和客户端添加列。因此，此服务不再将任一请求体建模为结构体：update_inbound 和 update_client 会将当前行读入映射，只删除面板在每次请求时重新计算的字段，再叠加所提供的参数——较新面板添加的任何字段都会原样保留，不会在下次更新时被静默清除。原样保留并不等同于可以设置，因此这些版本新增的客户端列——HWID 限制、每个客户端的重置周期、VLESS 反向标签，以及 MTProto、WireGuard 和 AmneziaWG 对等端设置——在 add_client 和 update_client 上都有各自的参数。完整列表请参阅 xui://docs/client-fields 资源。

v3.9.0 新增了一个路由——续订预览——并更改了入站更新可以修改的内容：inbounds/update 现在无论请求体中是什么值，都会保留已存储的客户端列表和入站的 enable 标志，因此 update_inbound 不再能关闭入站或编辑其客户端。请改用 set_inbound_enable 和客户端工具；在较旧的面板上，这些本来就是更安全的方式。同一版本还新增了每周配额续订（reset_weekday，不能与 reset 和 reset_day 同时使用——update_client 会清除退出模式的设置），并且除非设置了 allow_private，否则 get_remote_cert_hash 会拒绝私有或环回目标。

v3.10.0 没有新增路由——只新增了一项 Warp 操作和一种协议。manage_warp 接受 action=regMasque，用于通过 MASQUE 注册 Warp 设备；面板不存储任何内容，并会返回 warp-masque 出站所需的私钥、地址和端点。MASQUE 入站使用电子邮件和密码让客户端登录：在 add_client 中不提供 password 时，面板会生成一个密码；电子邮件中不能包含 :。同一版本将客户端的 WireGuard 对等端列（private_key、public_key、pre_shared_key、allowed_ips、keep_alive）移到了客户端所属的 WireGuard/AmneziaWG 入站下：对于不属于此类入站的客户端，update_client 仍会成功，但面板会保留已存储的值。负载均衡器覆盖现在可以在路由重新加载后继续生效（但核心重启后不会保留）；面板还会拒绝更多 Xray 无法运行的配置——大小不正确的 Shadowsocks-2022 密钥、少于 4 个字节的掩码密码、无法解析的报告或 LDAP cron。v3.10.2 未更改 API。 已针对当前的面板版本 v3.10.2 进行测试，此前也测试过 v3.9.0 和 v3.8.5。每个工具都在实际运行的面板上进行了测试：读取、写入、针对注册为节点的第二个面板运行的节点工具，以及针对确实提供列表的 URL 运行的出站订阅工具。有四个工具需要此服务无法凭空提供的配置——test_smtp 和 test_telegram_bot 需要凭据，delete_client_device 需要客户端应用注册的设备，get_node_cert_fingerprint 需要 HTTPS 节点——因此仅确认它们能访问面板并由面板响应，而非确认它们能成功执行。集成测试（make test-panel）通过对比更新前后的整个入站和整个客户端，验证了读-改-写约定。

MCP 工具

每个工具都标注了其对面板的影响——只读、附加、破坏性或会中断服务——以及是否会访问面板之外的主机。MCP 客户端会利用这些提示自动批准安全调用，并在执行其他调用前征求确认。

入站管理

15 个工具 — CRUD、启用切换、流量重置、回退规则、批量删除、链接

工具	描述
list_inbounds	列出所有入站连接
get_inbound	按 ID 获取入站
create_inbound	创建新的入站
update_inbound	更新现有入站
delete_inbound	删除入站
set_inbound_enable	启用或禁用入站，但不重写其设置
reset_inbound_traffic	将单个入站的流量计数器清零
delete_all_inbound_clients	从入站中移除所有客户端，同时保留该入站
bulk_delete_inbounds	一次调用删除多个入站
get_all_inbound_links	统计连接 URL 的数量，并提供完整列表的链接（full=true 会内嵌链接）
list_inbounds_slim	列出客户端数组经过精简的入站，适用于大型面板的低开销列表
get_inbound_options	选择器投影：id、备注、标记、协议、端口、能力标志
get_inbound_fallbacks	获取主 VLESS/Trojan TCP-TLS 入站上的回退规则
set_inbound_fallbacks	替换整个回退列表（会重启 Xray）
set_inbound_sub_sort_index	设置入站在订阅输出中的位置

### 客户端管理

客户端是以电子邮件地址为键的实体，可同时关联到多个入站配置。

41 个工具 — 按电子邮件地址执行 CRUD、关联/取消关联、批量操作、流量、设备、在线状态

工具	描述
add_client	创建客户端并将其关联到一个或多个入站配置（inbound_ids）
update_client	按电子邮件地址更新客户端（仅更改提供的字段；UUID 保持不变）
delete_client	按电子邮件地址删除客户端（可选 keep_traffic）
get_client	按电子邮件地址获取客户端的完整配置及其入站关联
list_clients	支持分页、搜索和筛选的客户端列表
attach_client	将现有客户端关联到更多入站配置
detach_client	取消客户端与指定入站配置的关联
bulk_create_clients	在相同的入站配置中创建多个客户端
bulk_delete_clients	按电子邮件地址删除多个客户端
get_client_traffic	按电子邮件地址获取客户端流量统计
get_client_ips	获取客户端使用过的 IP 地址
clear_client_ips	清除记录的客户端 IP 地址
reset_client_traffic	按电子邮件地址重置客户端流量计数器
reset_all_traffics	重置所有入站流量计数器
reset_all_client_traffics	重置所有客户端的流量（整个面板）
bulk_reset_traffic	重置指定客户端的流量
delete_depleted_clients	删除流量耗尽或已过期的客户端（整个面板）
get_online_clients	列出当前已连接的客户端
get_last_online	获取每个客户端最后在线的时间戳
update_client_traffic	设置客户端指定的上传/下载字节计数器
get_subscription_links	以 JSON 格式获取订阅 ID 下提供的连接 URL
get_client_links	按电子邮件地址获取单个客户端的连接 URL，每个入站配置一个
get_happ_link	为 Happ 应用生成加密的 happ://crypt5 链接，该链接封装了客户端的订阅
preview_client_renewal	查看配额续订计划下次触发的时间（按面板时区）；不会保存任何内容
get_clients_by_telegram_id	按 Telegram 用户 ID 查找客户端
list_client_devices	列出为客户端注册的 HWID 设备
delete_client_device	移除一个已注册设备，释放一个 HWID 名额
clear_client_devices	移除客户端的所有已注册设备
bulk_enable_clients	启用多个客户端；每个所属入站配置重写一次
bulk_disable_clients	禁用多个客户端；每个所属入站配置重写一次
bulk_adjust_clients	调整多个客户端的到期时间和配额 — 批量续订
delete_orphan_clients	删除未关联到任何入站配置的客户端及其记录
export_clients	统计客户端数量并提供完整导出内容的链接（full=true 时内联完整内容）
import_clients	从导出的数组创建客户端；跳过已存在的电子邮件地址
set_client_external_links	替换客户端的外部链接和订阅
list_clients_paged	在服务端对客户端进行筛选、排序和分页
bulk_attach_clients	一次将多个客户端关联到多个入站配置
bulk_detach_clients	一次取消多个客户端与多个入站配置的关联
get_active_inbounds	按节点分组，列出有流量经过的入站标签
get_online_clients_by_node	按服务节点分组列出在线客户端
get_client_ips_by_node	按观察到客户端连接的节点分组列出各客户端的源 IP 地址

### 服务器管理

14 个工具 — 状态、日志、Xray 服务控制、密钥生成、REALITY 扫描

工具	描述
server_status	获取服务器系统状态（CPU、RAM、磁盘、运行时间）
restart_xray	重启 Xray 服务
stop_xray	停止 Xray 服务
get_xray_config	概述正在运行的 Xray 配置，并提供完整 JSON 的链接（full=true 会内联显示）
get_xray_versions	列出可用的 Xray 版本
install_xray	安装指定的 Xray 版本
get_logs	获取面板服务日志
get_xray_logs	获取 Xray 核心日志
get_settings	获取面板设置
get_default_xray_config	获取默认 Xray 配置
restart_panel	重启 3x-ui 面板
generate_key	生成密钥材料：UUID、X25519（Reality）、VLESS 加密、ML-KEM-768、ML-DSA-65
scan_reality_target	探测一个 REALITY 候选项，并报告其是否可用
scan_reality_targets	探测域名、IP 或 CIDR 范围，并按可行性和延迟排序

Xray 配置

21 个工具 — 模板、路由规则、出站、负载均衡器、出站订阅

工具	描述
get_xray_template	概述模板，并提供完整 JSON 的链接（full=true 会内联显示）
update_xray_template	更新 Xray JSON 模板
get_routing_rules	列出所有路由规则（以及它们引用的负载均衡器）
add_routing_rule	添加路由规则
remove_routing_rule	按索引移除路由规则
update_routing_rule	按索引更新路由规则
get_outbounds	列出所有出站
get_outbounds_traffic	获取出站流量统计
reset_outbound_traffic	重置某个出站标签的流量
test_outbound	测试出站连通性
get_balancers	负载均衡器定义及其在运行中的核心内的实时状态
set_balancer_override	将负载均衡器固定到某个出站，或解除固定并恢复其策略
test_route	询问核心在模拟连接中会选择哪个出站
list_outbound_subs	列出出站订阅 — 提供额外出站的远程 URL
preview_outbound_sub	解析订阅 URL，但不保存
create_outbound_sub	添加出站订阅
update_outbound_sub	更新订阅（仅更改提供的字段）
refresh_outbound_sub	立即重新获取订阅并返回其出站
move_outbound_sub	上移或下移订阅的优先级
delete_outbound_sub	删除出站订阅

主机组

主机组会通过外部地址发布一个或多个入站，例如 CDN 主机名、另一个端口或不同的 SNI；面板会据此生成订阅链接。组通过字符串 group_id 标识。

11 个工具 — CRUD、排序、批量状态

工具	描述
list_hosts	列出所有入站中的每个主机组
get_host_group	按 ID 获取一个组
get_inbound_hosts	获取附加到一个入站的组
list_host_tags	列出各组中使用的不同标签
add_host_group	在一组入站上创建一个组
update_host_group	更新一个组，保留未提供的字段
delete_host_group	删除一个组及其主机
set_host_group_enable	启用或禁用一个组
reorder_host_groups	设置组的显示顺序
bulk_delete_host_groups	一次删除多个组
bulk_set_host_groups_enable	一次切换多个组的启用状态

add_host_group 和 update_host_group 提供组通常使用的字段；其他字段（mux、sockopt、ECH、final mask）可通过 raw_json 发送完整的 HostGroup。

订阅负载均衡器

客户端侧负载均衡器：每个负载均衡器都会出现在其某个入站的每位客户端的 JSON 订阅中，客户端应用会根据策略选择服务器。不要将其与 get_balancers 混淆；后者报告的是 Xray 内部运行的路由负载均衡器。

4 tools — 按排序顺序执行 CRUD

工具	描述
list_sub_balancers	按排序顺序列出所有订阅负载均衡器
create_sub_balancer	在一组入站上添加一个负载均衡器
update_sub_balancer	更新一个负载均衡器，并保留未指定的字段
delete_sub_balancer	移除一个负载均衡器

API 令牌

4 tools — 创建、停用、删除

工具	描述
list_api_tokens	令牌元数据；绝不返回令牌值本身
create_api_token	创建限定范围的令牌 — 明文仅显示一次
set_api_token_enabled	停用或重新启用令牌，但不删除它
delete_api_token	永久删除令牌

delete_api_token 和 set_api_token_enabled 需要提供令牌已存储的 scope；如果不匹配，面板会默认拒绝操作，因此无法通过猜测令牌 ID 来切换令牌状态。

出站提供商

Cloudflare Warp、NordVPN 和 PIA 各自都有一个读取工具和一个写入工具，因此查询国家/地区列表与擦除凭据时会有不同的注解。

6 tools — 每个提供商各有一个读取工具和一个写入工具

工具	描述
get_warp_data	Warp 帐户状态或已存储的 WireGuard 配置
manage_warp	注册（WireGuard 或 MASQUE）、轮换 IP、应用许可证、设置轮换，或擦除
get_nordvpn_data	国家/地区、某个国家/地区内的服务器，或已存储的帐户
manage_nordvpn	使用令牌注册、设置密钥，或擦除
get_pia_data	区域、某个区域内的服务器，或已存储的帐户
manage_pia	登录、为某台服务器注册密钥，或擦除

面板维护

19 tools — 健康状态、证书、地理数据文件、自我更新、备份、集成测试

工具	描述
get_fail2ban_status	此主机能否强制执行按客户端划分的 IP 限制
get_web_cert_files	此面板自身的 TLS 证书和密钥路径
get_cert_hash	证书的 SHA-256 值，用于证书固定
get_remote_cert_hash	远程服务当前证书的 SHA-256 值
generate_ech_cert	为一个 SNI 生成 ECH 密钥对和配置列表
update_geofile	下载最新的 GeoIP/GeoSite 数据文件
get_panel_update_status	上次面板自我更新的结果
set_update_channel	在 stable 和 dev 通道之间切换
update_panel	对面板执行自我更新（随后会重启）
get_amneziawg_logs	AmneziaWG 对等端的实时活动和事件
get_node_descendants	集群树中位于此面板下方的节点
get_client_ips_table	IP 限制所用的聚合客户端 IP 表
backup_to_telegram	将数据库备份发送到管理员的 Telegram 聊天
test_smtp	测试 SMTP，并逐阶段报告结果
test_telegram_bot	通过已配置的机器人发送测试消息
validate_regex	使用面板的 Go RE2 引擎编译模式
get_default_settings	预览全新安装时会计算出的设置
get_factory_defaults	随附的各设置键默认值
update_admin_credentials	更改面板管理员用户名和密码

update_admin_credentials 会使此服务器自身使用的凭据失效：更新 XUI_USERNAME / XUI_PASSWORD 并在之后重启服务器，或者先切换为使用 API 令牌。

多节点

节点是此面板驱动的另一个 3x-ui 面板：入站和客户端会推送到该节点，流量则会拉取回来。这些调用大多直接发往节点本身，而不只是此面板。

16 tools — CRUD、探测、mTLS、节点面板更新

Tool	Description
list_nodes	已配置节点的健康状况、数量和上次心跳
get_node	单个节点的连接详情和同步状态
get_node_history	单个节点的 CPU 或内存历史记录
get_node_web_cert	节点上现有的证书和密钥路径
test_node	探测连接详情，但不保存
list_node_inbounds	节点上可用的入站，用于选择性同步
get_node_cert_fingerprint	节点叶证书的 SHA-256 值，用于证书固定
add_node	注册节点（保存前会先探测）
update_node	更新节点，保留未提供的字段
set_node_enable	暂停或恢复与节点的流量同步
probe_node	探测已注册节点并刷新其缓存健康状态
delete_node	删除节点；其入站不会迁移
get_node_mtls_ca	此面板的节点身份验证 CA，首次调用时生成
set_node_mtls_trust_ca	此面板作为节点时信任的 CA
reload_node_mtls_client	应用轮换后的客户端证书，无需重启
update_node_panels	在指定节点上运行 3x-ui 自更新程序

从 v3.6.0 起，节点 API 令牌只能写入，无法读取：面板只会报告是否已设置令牌，因此除非传入新令牌，否则 update_node 会省略该字段；迁移到 mTLS 的节点可通过 clear_api_token 删除旧令牌。

客户端组

组是一个标签，同时记录在客户端记录和每个所属入站的设置中；面板会在一个事务中保持两者同步。

8 tools — CRUD 和批量成员管理

Tool	Description
list_client_groups	所有组及其成员数量，包括空组
get_client_group_emails	单个组中的邮箱 — 批量操作的输入
create_client_group	创建一个可供选择的空组
rename_client_group	重命名组并重新关联所有成员
delete_client_group	删除组，但保留其客户端
add_clients_to_group	使用同一个组标记多个客户端
remove_clients_from_group	清除多个客户端的组标签
reset_client_group_traffic	将组计数器归零，同时继续运行各客户端的计数器

可观测性

6 tools — 指标历史记录、observatory、更新检查

Tool	Description
get_metrics_history	单个主机指标的时间序列（cpu、mem、netUp/Down、online、load）
get_xray_metrics	Xray 运行时指标状态和当前 expvar 值
get_xray_metrics_history	单个 Xray 运行时指标的时间序列
get_xray_observatory	最新的各出站延迟和健康状况快照
get_xray_observatory_history	单个出站标签随时间变化的探测结果
get_panel_update_info	是否有更新版本的 3x-ui 发布

历史记录工具接收以秒为单位的 bucket，并始终返回 60 个样本，因此 bucket 也决定时间窗口：2（2m）、30（30m）、60（1h）、180（3h）、360（6h）、720（12h）、1440（24h）、2880（2d）、10080（7d）。

地理数据

4 个工具 — 浏览地理数据库，验证路由令牌

工具	描述
list_geodata_files	Xray 资源文件夹中的地理数据库，包含布局和类别数量
list_geodata_categories	单个数据库中的类别，包含条目数量和属性
list_geodata_entries	类别中的规则——类型化域名或 CIDR
validate_geodata_tokens	报告无法解析的路由令牌，并说明原因

有意不封装： server/getDb、server/getMigration 和 server/importDB 会将数据库文件作为附件和多部分上传内容传输， 因此更适合放在浏览器或备份脚本中，而不是这里。 inbounds/pushClientTraffics 和 POST server/clientIps 是节点同步的入站部分—— 节点接收请求的端点，而不是客户端调用的端点。

资源

无论调用方是否需要所有结果，工具都会消耗上下文。 资源则相反：每个资源在 resources/list 中只占一行，只有在有人请求其 URI 时才会读取。 体积最大的三个工具会返回摘要，以及指向相应资源的 resource_link——运行中的 Xray 配置约有 9k 个字符，而其摘要不到 500 个字符。

URI	内容
xui://docs/inbound-settings	设置、streamSettings 和 sniffing JSON，每种协议附有一个示例
xui://docs/client-fields	各个客户端字段的含义及其所用单位
xui://xray/config	核心当前正在运行的配置
xui://xray/template	已保存的模板：路由、负载均衡器、出站、DNS
xui://inbounds	所有入站，包含设置和每个客户端的统计信息
xui://inbounds/links	每个客户端的连接 URL
xui://clients/export	所有客户端，格式为 {client, inboundIds}，包含凭据
xui://inbound/{id}	按数字 ID 查询单个入站
xui://client/{email}	按电子邮件查询单个客户端记录

两个 xui://docs/… 资源是静态参考文本，因此读取它们不会调用面板。

架构

cmd/xui-mcp/main.go        Entry point, config loading, signal handling
internal/config/            Configuration from environment variables
internal/xui/              HTTP client with session management
internal/handler/          MCP tool definitions and request handlers

开发

make test       # Run tests
make lint       # Run golangci-lint (config in .golangci.yml)
make fmt        # Format code
make build      # Build binary

参与贡献

欢迎提交 Bug 报告、面板版本相关发现和拉取请求——请参阅 CONTRIBUTING.md，了解环境配置、CI 运行的检查，以及新工具必须遵循的面板约定。 参与项目须遵守 Code of Conduct；如发现漏洞，请按照 SECURITY.md 中的说明处理，而不要创建 issue。 每个版本的变更内容，包括工具数量及所需的面板版本，请参阅 CHANGELOG.md。

许可证

MIT