WSL-MCP

一个支持持久化会话和终端轮询的 MCP (Model Context Protocol) 终端管理服务器。

特性

• WSL 原生支持 - 专门针对 Windows + WSL 环境优化
• Docker 后端支持 - 支持容器化隔离环境
• 持久化会话 - 终端会话保持，环境变量和工作目录持久化
• 终端轮询 - 支持长时间运行进程的输出轮询（核心创新功能）
• 日志跟踪 - 类似 tail -f 的日志持续输出功能
• 文件传输 - 支持文件上传/下载（Base64 编码）
• 多后端支持 - 默认自动检测：WSL 优先 → Docker 备选，也可显式指定 backend

安装

使用 npx（推荐）

无需安装，直接使用 npx 运行：

npx wsl-mcp

在 MCP 客户端中配置

在 MCP 客户端（如 Claude Desktop、Kilo Code 等）配置中添加：

{
  "mcpServers": {
    "wsl-mcp": {
      "command": "npx",
      "args": ["-y", "wsl-mcp"],
      "env": {
        "WSL_MCP_WSL_DISTRIBUTION": "Ubuntu"
      }
    }
  }
}

注意: 使用 -y 标志可以自动确认 npx 的安装提示，适合自动化场景。

全局安装

npm install -g wsl-mcp
wsl-mcp

从源码安装

# 克隆仓库
git clone https://github.com/cacaview/wsl-mcp.git
cd wsl-mcp

# 安装依赖
npm install

# 构建
npm run build

环境变量

变量名	描述	默认值
WSL_MCP_BACKEND	后端类型 (auto/wsl/docker/msys2)	auto
WSL_MCP_WSL_DISTRIBUTION	WSL 发行版名称	默认发行版
WSL_MCP_MAX_SESSIONS	最大会话数	10
WSL_MCP_DEFAULT_TIMEOUT	默认超时时间 (ms)	30000

MCP 工具

命令执行

terminal_execute

在持久化终端会话中执行命令。

{
  "command": "ls -la",
  "session_id": "default",
  "timeout": 30000
}

后台进程管理

terminal_start_process

启动后台进程并开始轮询输出。

{
  "command": "npm run dev",
  "session_id": "default",
  "poll_interval": 1000
}

terminal_poll_output

获取后台进程的输出。

{
  "process_id": "xxx-xxx-xxx",
  "incremental": true
}

terminal_stop_process

停止后台进程。

terminal_list_processes

列出所有后台进程。

日志跟踪

terminal_tail_logs

开始跟踪日志文件。

{
  "file_path": "/var/log/app.log",
  "lines": 100,
  "follow": true
}

terminal_get_logs

获取跟踪的日志内容。

terminal_stop_tail

停止日志跟踪。

会话管理

terminal_new_session

创建新的终端会话。

terminal_list_sessions

列出所有会话。

terminal_close_session

关闭会话。

文件传输

terminal_upload_file

上传文件到远程系统（Base64 编码）。

{
  "remote_path": "/home/user/file.txt",
  "content": "SGVsbG8gV1NMLU1DUA==",
  "mode": "644",
  "overwrite": true
}

terminal_download_file

从远程系统下载文件（返回 Base64 编码）。

{
  "remote_path": "/home/user/file.txt",
  "max_size": 10485760
}

terminal_list_directory

列出远程目录内容。

{
  "path": "/home/user",
  "recursive": false
}

系统信息

get_system_info

获取系统信息（操作系统、Shell、用户等），并返回当前选中的 backend、检测到的 backend 列表以及选择模式（auto/explicit）。

get_directory_info

获取目录信息（路径、是否存在、文件列表）。

开发

# 开发模式
npm run dev

# 运行测试
npm test

# 类型检查
npm run typecheck

# 代码检查
npm run lint

架构

src/
├── index.ts          # 入口文件
├── server.ts         # MCP 服务器
├── backends/         # 后端实现
│   ├── types.ts      # 类型定义
│   ├── wsl.ts        # WSL 后端
│   ├── docker.ts     # Docker 后端
│   └── index.ts      # 后端工厂
├── session/          # 会话管理
│   ├── types.ts
│   └── manager.ts
├── polling/          # 轮询机制
│   ├── types.ts
│   ├── output-poller.ts
│   └── log-tailer.ts
├── transfer/         # 文件传输
│   ├── types.ts
│   └── manager.ts
├── utils/            # 工具函数
│   ├── errors.ts
│   └── output.ts
└── tools/            # MCP 工具
    ├── definitions.ts
    └── handlers.ts

许可证

MIT