AI导哈

终端命令执行服务

一个允许AI代理在主机系统上执行终端命令的MCP服务器，支持跨平台操作和安全限制。

  • by atman-33
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 atman-33/mcp-terminal-runner

使用说明

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：标准误差。

发展

设置

  1. 克隆存储库：
git clone <repository-url>
cd mcp-terminal-runner
  1. 安装依赖项：
npm install
  1. 构建项目：
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许可证-有关详细信息，请参阅许可证文件。

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 跑 npm run quality 确保代码质量
  5. 提交您的更改（赫斯基将运行预提交钩子）
  6. 推到您的分支
  7. 创建拉取请求

故障排除

常见问题

  1. 服务器未启动：确保安装了所有依赖项并构建了项目
  2. 工具未出现：检查MCP客户端配置是否指向正确的路径
  3. 权限错误：确保构建的JavaScript文件具有执行权限

调试模式

要启用调试日志记录，请设置环境变量：

DEBUG=mcp* npm start

相关 MCP