AI导哈

终端执行服务器

MCP终端服务器是一个安全的终端执行服务器，提供受控的命令执行能力，具有安全控制和资源限制功能。

  • by RinardNick
  • JavaScript
  • 本地部署
  • 11 星标
  • 更新于
在 GitHub 查看 RinardNick/mcp-terminal

使用说明

MCP终端服务器

实现模型上下文协议（MCP）的安全终端执行服务器。此服务器提供具有安全功能和资源限制的受控命令执行功能。

特性

  • 命令执行：执行带有输出捕获和错误处理的shell命令
  • 安全控制：限制允许的命令并防止命令注入
  • 资源控制:
    • 命令超时
    • 最大输出大小限制
  • MCP协议支持:
    • 标准MCP消息格式
    • 能力广告
    • 流输出支持

发展

本地设置

# Clone the repository
git clone https://github.com/RinardNick/mcp-terminal.git
cd mcp-terminal

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install development dependencies
uv pip install -e ".[dev]"

发布到PyPI

# Build the package
uv pip install build
python -m build

# Upload to PyPI
uv pip install twine
python -m twine upload dist/*

MCP检验员测试

MCP检查器工具可用于测试服务器实现：

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Test server
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"

运行测试

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_terminal.py

# Run with coverage
pytest --cov=mcp_terminal tests/

与Claude Desktop一起使用

一旦包发布到PyPI：

  1. 安装UV （如果尚未安装）：

    pip install uv

  2. 使用UV安装软件包:

    uv pip install mcp-terminal

  3. 配置Claude桌面: 编辑您的Claude Desktop配置文件（通常在 ~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上：

    {
  "mcpServers": {
    "terminal": {
      "command": "uv",
      "args": [
        "pip",
        "run",
        "mcp-terminal",
        "--allowed-commands",
        "python,pip,git,ls,cd",
        "--timeout-ms",
        "30000",
        "--max-output-size",
        "1048576"
      ]
    }
  }
}

协议实现

服务器实现了具有以下功能的模型上下文协议（MCP）：

能力广告

{
  "protocol": "1.0.0",
  "name": "terminal",
  "version": "1.1.0",
  "capabilities": {
    "execute": {
      "description": "Execute a terminal command",
      "parameters": {
        "command": {
          "type": "string",
          "description": "The command to execute"
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "exitCode": { "type": "number" },
          "stdout": { "type": "string" },
          "stderr": { "type": "string" },
          "startTime": { "type": "string" },
          "endTime": { "type": "string" }
        }
      }
    }
  }
}

消息格式

请求:

{
  "type": "execute",
  "data": {
    "command": "echo 'hello world'"
  }
}

响应:

{
  "type": "result",
  "data": {
    "command": "echo 'hello world'",
    "exitCode": 0,
    "stdout": "hello world\n",
    "stderr": "",
    "startTime": "2024-01-20T12:34:56.789Z",
    "endTime": "2024-01-20T12:34:56.790Z"
  }
}

错误:

{
  "type": "error",
  "data": {
    "message": "command not allowed"
  }
}

安全考虑

  1. 命令验证:

    • 只能执行允许的命令
    • 壳牌运营商受阻
    • 命令注入尝试被阻止

  2. 资源保护:

    • 命令超时防止挂起
    • 输出大小限制可防止内存耗尽
    • 所有故障情况的错误处理

  3. 最佳实践:

    • 始终设置 allowed-commands 生产中
    • 使用保守的超时和大小限制
    • 监视命令执行日志

贡献

  1. 分叉存储库
  2. 创建功能分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add some amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP