内容
Local Opsecured Build: [](https://github.com/opsecured/wsl-mcp/actions/workflows/release.yml)
Independent Build: [](https://github.com/riparino/wsl-mcp/actions/workflows/release.yml)
# @modelcontextprotocol/server-wsl
一款 [MCP 服务器](https://modelcontextprotocol.io)，为 Claude Desktop 提供对 Windows 子系统 for Linux（WSL）环境的完全访问权限。可以在 WSL 中运行命令、读取和写入文件，以及检查发行版 - 所有这些都可以在 Windows 上的 Claude 对话中完成。
## 先决条件
- **Windows 10 版本 2004+ 或 Windows 11**
- 已安装 **WSL 2**（在管理员 PowerShell 中运行 `wsl --install`）
- 通过 Microsoft Store 或 `wsl --install -d <Distro>` 安装 **至少一个 Linux 发行版**
- **Node.js 18 或更高版本**（用于从源代码构建）
## 安装
### 从 npm（推荐）
```bash
npm install -g @modelcontextprotocol/server-wsl
```
### 从源代码
```bash
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/wsl
npm install
npm run build
```
## 配置
将服务器添加到您的 Claude Desktop 配置文件中。
**配置文件位置：**
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
### 使用 npx（零安装）
```json
{
"mcpServers": {
"wsl": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-wsl"]
}
}
}
```
### 使用全局安装的软件包
```json
{
"mcpServers": {
"wsl": {
"command": "mcp-server-wsl"
}
}
}
```
### 直接在 WSL 中运行（替代方案）
如果您更喜欢在 WSL 中运行服务器，可以通过 `wsl.exe` 调用它：
```json
{
"mcpServers": {
"wsl": {
"command": "wsl.exe",
"args": ["node", "/path/to/wsl-mcp/dist/index.js"]
}
}
}
```
编辑配置文件后，重启 Claude Desktop。您应该在 Claude 工具选择器中看到 WSL 工具。
## 可用工具
| 工具 | 描述 |
|---|---|
| `list_distros` | 列出所有已安装的 WSL 发行版、它们的状态（运行/停止）、WSL 版本和默认发行版 |
| `run_command` | 在 WSL 发行版中执行 bash 命令；返回 stdout、stderr 和退出代码 |
| `read_file` | 从 WSL 文件系统中按绝对路径读取文本文件 |
| `write_file` | 在 WSL 文件系统中写入或覆盖文件 |
| `list_directory` | 列出目录内容，包括名称、类型、权限、大小和时间戳 |
| `get_distro_info` | 获取有关发行版的详细信息：WSL 版本、状态、内核、OS 版本、当前用户 |
### 工具参数
#### `run_command`
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `command` | 字符串 | ✅ | 要运行的 bash 命令（传递给 `bash -c`） |
| `distro` | 字符串 | | 发行版名称；默认为默认发行版 |
| `timeout_ms` | 数字 | | 命令被终止前的毫秒数；默认为 30,000 |
#### `read_file`
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `path` | 字符串 | ✅ | WSL 文件系统中的绝对路径 |
| `distro` | 字符串 | | 发行版名称；默认为默认发行版 |
#### `write_file`
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `path` | 字符串 | ✅ | WSL 文件系统中的绝对路径 |
| `content` | 字符串 | ✅ | 要写入的 UTF-8 文本内容 |
| `distro` | 字符串 | | 发行版名称；默认为默认发行版 |
#### `list_directory`
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `path` | 字符串 | ✅ | 目录的绝对路径 |
| `distro` | 字符串 | | 发行版名称；默认为默认发行版 |
#### `get_distro_info`
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `distro` | 字符串 | | 发行版名称；默认为默认发行版 |
## 示例提示
连接后，尝试询问 Claude：
- *"我有哪些 WSL 发行版已安装？"*
- *"在我的 Ubuntu 发行版中运行 `df -h` 并显示磁盘使用情况"*
- *"从 WSL 读取文件 `/etc/hosts`"*
- *"在 `/home/user/hello.py` 处创建一个 Python 脚本，打印 Hello, World"*
- *"列出我的 WSL 主目录的内容"*
- *"我的 WSL 实例正在运行哪个内核版本？"*
## 安全考虑
- 命令作为所选发行版的**默认用户**（通常是您的常规 Linux 用户，而不是 root）执行。
- 没有路径沙盒 - Claude 可以读取和写入 WSL 用户有权访问的任何文件。仅将此 MCP 服务器授予受信任的 Claude 对话。
- 命令输出被限制在 **10 MB** 以防止失控的进程压倒主机。
- 默认命令超时为 **30 秒**；使用 `timeout_ms` 为长时间运行的任务增加超时时间。
## 故障排除
**"wsl.exe 未找到"**
WSL 未安装或不在系统 PATH 中。在管理员 PowerShell 中运行 `wsl --install`。
**"未配置默认 WSL 发行版"**
您已安装 WSL 但未设置默认发行版。使用以下命令修复：`wsl --set-default <DistroName>`
**发行版显示为已停止但命令仍然有效**
这是预期的 - WSL 在运行命令时会自动启动已停止的发行版。
**UTF-8 输出看起来乱码**
一些较旧的 Windows 版本将 WSL 列表输出为 UTF-16 LE。服务器会自动规范化此输出；如果您仍然遇到问题，请确保您的 WSL 已更新到最新版本（`wsl --update`）。
## 许可证
MIT
