MCP 终端服务器

一个实现了模型上下文协议 (MCP) 的安全终端执行服务器。该服务器提供具有安全特性和资源限制的受控命令执行能力。

特性

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

开发

本地设置

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

# 使用 uv 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # 或 Windows 上的 .venv\Scripts\activate

# 安装开发依赖
uv pip install -e ".[dev]"

发布到 PyPI

# 构建包
uv pip install build
python -m build

# 上传到 PyPI
uv pip install twine
python -m twine upload dist/*

使用 MCP Inspector 进行测试

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

# 安装 inspector
npm install -g @modelcontextprotocol/inspector

# 测试服务器
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"

运行测试

# 运行所有测试
pytest tests/

# 运行特定测试文件
pytest tests/test_terminal.py

# 运行并生成覆盖率报告
pytest --cov=mcp_terminal tests/

与 Claude Desktop 一起使用

将软件包发布到 PyPI 后：

1. 安装 UV (如果尚未安装):

   pip install uv
   

2. 使用 UV 安装软件包:

   uv pip install mcp-terminal
   

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

   {
     "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": "执行终端命令",
      "parameters": {
        "command": {
          "type": "string",
          "description": "要执行的命令"
        }
      },
      "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. 命令验证:

   • 只能执行允许的命令
   • Shell 操作符被阻止
   • 防止命令注入尝试

2. 资源保护:

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

3. 最佳实践:

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

贡献

1. Fork 仓库
2. 创建您的特性分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。