MCP终端运行器
允许AI代理在主机系统上执行终端命令的MCP服务器。
特性
- 执行命令：运行shell命令并检索stdout、stderr和退出代码。支持管道、重定向和命令链（例如。，
&&). - 执行进程（argv）：使用argv样式的输入运行程序（无shell解析）。可用于安全传递大/多行参数。
- 安全：通过严格的对抗制度
ALLOWED_COMMANDS环境变量。 - 超时：命令有一个默认超时（30000毫秒），以防止无限期挂起。
- 交叉平台的：适用于Linux、macOS和Windows。
先决条件
- Node.js（版本18或更高）
配置
安全：允许的命令
出于安全原因，此服务器需要一个明确的允许命令列表。这是通过配置的 ALLOWED_COMMANDS 环境变量。
- 格式：逗号分隔的命令二进制文件列表（例如。，
ls,cat,echo). - 通配符：设置为
*允许所有命令(⚠️ 危险：仅在受信任的环境中使用）。 - 验证：服务器仅验证 第一个命令 在对抗排外主义的链条上。例如，在
echo hello && ls，仅echo已检查。
安全（可选）：允许的工作目录根
您可以选择通过以下方式限制允许使用的工作目录 ALLOWED_CWD_ROOTS.
- 格式：以逗号分隔的允许根路径列表。
- 行为:
- 如果 未设置或为空, cwd 不受限制（允许使用任何现有目录）。 - 如果设置，则解析和规范 cwd 必须位于至少一个配置的根目录内。 - 如果set和任何配置的root都无法规范化（例如，不存在），则请求提供 cwd 被拒绝（配置错误）。
用法
MCP客户端配置
将以下内容添加到MCP客户端配置中（例如，VS代码 settings.json):
基本配置
{
"mcpServers": {
"terminal-runner": {
"command": "npx",
"args": ["-y", "mcp-terminal-runner"],
"env": {
"ALLOWED_COMMANDS": "ls,cat,grep,echo"
}
}
}
}配置允许的工作目录
{
"mcpServers": {
"terminal-runner": {
"command": "npx",
"args": ["-y", "mcp-terminal-runner"],
"env": {
"ALLOWED_COMMANDS": "ls,cat,grep,echo",
"ALLOWED_CWD_ROOTS": "/home/user/projects,/tmp"
}
}
}
}可用工具
execute_command
执行shell命令。注意：此工具仅适用于非交互式、短暂的命令。不支持交互式命令。
- 输入:
- command （string）：要执行的shell命令。 - cwd （string）：在其中执行命令的工作目录。 - input （string，可选）：写入stdin的可选输入。适用于需要用户交互的命令。 - timeout_ms （数字，可选）：超时时间（毫秒）。默认值为30000ms。最大600000ms。
- 输出:
- 返回一个YAML格式的字符串，其中包含： - exit_code：命令的退出代码。 - stdout：标准输出。 - stderr：标准误差。
超时时，工具返回 isError: true 并且包括超时消息。
execute_process
使用argv风格的输入（非shell）执行程序。注意：此工具仅适用于非交互式、短暂的命令。不支持交互式命令。
当您需要传递大型或多行参数时（例如。， --content 不处理shell引用。
- 输入:
- file （string）：要执行的程序（例如。， python3). - args （string\[\]，可选）：传递给程序的argv参数。 - cwd （string）：在其中执行命令的工作目录。 - input （string，可选）：写入stdin的可选输入。 - timeout_ms （数字，可选）：超时时间（毫秒）。默认值为30000ms。最大600000ms。
- 输出:
- 返回一个YAML格式的字符串，其中包含： - exit_code：命令的退出代码。 - stdout：标准输出。 - stderr：标准误差。
发展
设置
- 克隆存储库：
git clone
cd mcp-terminal-runner- 安装依赖项：
npm install- 构建项目：
npm run build可用脚本
npm run build-构建TypeScript项目npm run dev-以开发模式运行npm start-运行构建的JavaScript版本npm run check-使用Ultracite检查代码npm test-使用Vitest运行测试
项目结构
mcp-terminal-runner/
├── src/
│ └── index.ts # Main server implementation
├── dist/ # Built JavaScript files
├── .husky/ # Git hooks
├── biome.json # Biome configuration
├── tsconfig.json # TypeScript configuration
├── package.json # Project dependencies and scripts
└── README.md # This file许可证
MIT许可证-有关详细信息，请参阅许可证文件。
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 跑
npm run quality确保代码质量 - 提交您的更改（赫斯基将运行预提交钩子）
- 推到您的分支
- 创建拉取请求
故障排除
常见问题
- 服务器未启动：确保安装了所有依赖项并构建了项目
- 工具未出现：检查MCP客户端配置是否指向正确的路径
- 权限错误：确保构建的JavaScript文件具有执行权限
调试模式
要启用调试日志记录，请设置环境变量：
DEBUG=mcp* npm start