vshell-mcp

把 v_shell 管理平台 的命令控制、文件管理、隧道代理、监听管理、客户端生成等能力封装为 MCP Server(SSE 传输),让 AI 可以直接操作平台上的任意受管主机。

✨ 功能特性

• 服务器信息:查看当前连接配置(URL / 账号)、登录用户、服务端版本与授权
• 仪表盘指标:客户端/监听/代理数量、在线数、CPU/内存/磁盘/负载、带宽、TCP/UDP 连接数
• 主机管理:列出所有受管主机(在线/离线、系统、IP、用户、归属地)
• 命令控制:在任意主机上执行 shell 命令(支持管道/重定向/workdir/超时)
• 文件管理:列目录、读写文件、新建/删除/重命名、上传/下载、URL 下载(wget)
• 隧道代理:隧道/代理的增删改查、启用/停用、改备注
• 监听管理:查看与新增监听器(按需求不提供删除功能)
• 客户端生成:生成并下载客户端(stage 反向 / listen 正向 / stageless / shellcode / dll / ebpf 等)

共 27 个工具,全部通过官方 MCP SDK 与真实 v_shell 实例端到端验证。

工作原理

AI 客户端(Claude Code 等)
   │  MCP over SSE  (type: sse, url: http://:19080/sse)
   ▼
vshell-mcp  (本仓库,Go 编写)
   │  HTTP API: /api/login、/api/client/list、/api/file/*、/api/tunnel/*(POST JSON)
   │  WebSocket: /api/terminal/ws(交互式终端,用于命令控制)
   ▼
v_shell 平台  (http://:8082)

• 命令控制:复用 v_shell 管理台的终端 WebSocket(/api/terminal/ws)。每条命令开启一次交互式 shell, 先 stty -echo 关闭回显、固定 prompt,再用 MCPB_* / MCPD_* 唯一标记夹取命令,返回纯 stdout。
• 文件/隧道:直接调用 v_shell 的 /api/file/*、/api/tunnel/* HTTP 接口。
• 认证:启动时用账号密码登录换取 JWT(Token: 请求头),过期自动重新登录。

环境要求

• Go 1.24+(仅构建时需要;运行只需要编译好的二进制)
• 运行机器能访问 v_shell 平台的 Web 地址(HTTP / HTTPS 均可)

构建

go build -o vshell-mcp .
# 或
./run.sh          # 未编译时脚本会自动编译

配置与启动

全部通过命令行参数配置,无需任何环境变量:

./vshell-mcp -h http://your-vshell-server:8082 -u admin -p 'your_password'

*:设置了 -token 则账号密码可省;否则 -p 必填(-u 默认 admin)。 ⚠️ -h 已绑定为 v_shell 地址参数(非 help);查看帮助请用 -help。

启动时先做一次登录/连通性校验,凭据错误会直接报错退出。正常启动:

v_shell MCP server listening on :19080  (SSE endpoint: http://127.0.0.1:19080/sse)

接入 AI 客户端

Claude Code

claude mcp add vshell --type sse --url http://127.0.0.1:19080/sse

或写入项目 .mcp.json / ~/.claude.json:

{
  "mcpServers": {
    "vshell": {
      "type": "sse",
      "url": "http://127.0.0.1:19080/sse"
    }
  }
}

MCP 服务运行在其它机器时,url 填该机器的地址与端口;若开了 -mcpurl,填它生成的地址。

其它支持 SSE MCP 的客户端

通用配置:type: sse,url: http://:19080/sse。

工具清单(27 个)

通用说明:host_id 为「客户端管理」里的主机 Id(见 list_hosts);local_path 等本地路径均指 MCP 服务器所在机器 的路径。

服务器信息(2)

主机与命令控制(2)

文件管理(12)

隧道 / 代理(8,对应 /tunnel/list)

监听器(2,对应 /listener/list)

按需求:仅支持查看与新增,禁止删除监听器(未提供删除工具)。

客户端生成(1,对应 /download 客户端生成页)

(* = 必填;? = 可选)

测试

# 对真实 v_shell 实例跑完整冒烟(需配好 -h -u -p)
VSHELL_URL=http://your-vshell-server:8082 VSHELL_USERNAME=admin VSHELL_PASSWORD=xxx \
  go run ./cmd/smoke

# 用官方 MCP Python SDK 连接运行中的 MCP 服务并调用工具
python3 tests/client_smoke.py

项目结构

.
├── main.go                 入口:命令行参数解析、登录校验、启动 SSE 服务
├── internal/
│   ├── vshell/             v_shell 客户端
│   │   ├── client.go       HTTP 封装(登录、Token 刷新、统一响应解析)
│   │   ├── terminal.go     终端 WebSocket 命令执行
│   │   ├── files.go        文件管理操作
│   │   ├── tunnel.go       隧道/代理管理操作
│   │   ├── listener.go     监听器管理操作(仅查看/新增,无删除)
│   │   ├── client_gen.go   客户端生成/下载
│   │   ├── dashboard.go    服务器信息与仪表盘
│   │   └── types.go        数据结构
│   └── mcp/server.go       MCP 工具定义与处理器
├── cmd/smoke/main.go       冒烟测试程序
├── tests/client_smoke.py   官方 MCP SDK 验证脚本
├── docs/API_NOTES.md       v_shell Web API 逆向笔记
└── run.sh                  启动脚本(自动编译 + 参数透传)

安全说明

• 本工具能执行任意命令、增删文件与隧道,属于强能力工具,请只对你自己拥有管理权限的 v_shell 平台使用。
• get_server_info 会把登录密码原样返回给 AI 客户端。若不需要回显密码,可自行改动 internal/mcp/server.go 的 handlerServerInfo,将 connection.password 置为 "******"。
• 命令控制走的是目标主机的真实 shell,交互式程序(vim、passwd、top 等)会卡住,请用非交互命令。
• 启动参数中的密码会出现在进程命令行(ps 可见),生产环境建议结合密钥管理或 -token 使用。

常见问题

• 启动报"无法连接 v_shell" — 检查 -h 地址是否可达、-u/-p 是否正确、账号是否有权。
• execute_command 返回空 / 超时 — 目标主机可能离线(IsConnect=false),或命令是交互式程序。 耗时命令在调用时调大 timeout_seconds 参数(如 timeout_seconds=300)。
• download_file 失败 — 文件在主机侧须存在且当前用户可读;下载是异步任务,大文件需等待轮询完成。
• add_tunnel 报参数错误 — 检查:mode=tcp/udp 必须给 target;port 不能与已有隧道/服务端口冲突。
• MCP 客户端连接不上 — 确认 MCP 服务器已启动且端口可访问;检查防火墙;用了 -mcpurl 时确认对外地址可达。