MCP 终端服务器

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

功能

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

开发

本地设置

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

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

# 安装开发依赖项
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 配置文件（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上）：

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

协议实现

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

功能广告

{
  "protocol": "1.0.0",
  "functions": {
    "terminal": {
      "type": "terminal",
      "version": "1.0"
    }
  }
}

消息格式

所有消息都遵循以下结构：

{
  "id": string,
  "command": string,
  "args": array,
  "result": any,
  "error": string | null
}

安全考虑

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

贡献

1. 叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加一些很棒的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据 MIT 许可证授权，详细信息请参阅 LICENSE 文件。