JinDaGe - mcp-terminal MCP Details

article

README

🚀 MCP 终端服务器

MCP 终端服务器是一个安全的终端执行服务器，实现了模型上下文协议（MCP）。它提供受控命令执行功能，具备安全功能和资源限制，能有效保障命令执行的安全性和稳定性。

🚀 快速开始

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 工具测试服务器：

# 安装 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，可按以下步骤使用：

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

pip install uv

使用 UV 安装包：

uv pip install mcp-terminal

配置 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 在生产环境中，确保只有安全的命令可以执行。
使用保守的超时和大小限制，避免资源过度占用。
监控命令执行日志，及时发现和处理异常情况。

🤝 贡献

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

📄 许可证

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

mcp-terminal