Terminal MCP Server

终端 MCP 服务

一个简单的 MCP 服务，可执行终端命令并提供终端命令速查表。同时演示 MCP 服务实现中可能存在的安全漏洞。

功能

1. 终端命令执行

   • 执行任意终端命令
   • 获取 stdout、stderr 和返回码
   • 错误处理

2. 安全漏洞演示

   • magical_tool 演示不安全的命令执行
   • 展示恶意代码如何被执行
   • 强调安全实现的重要性

3. 终端命令速查表

   • 30 个必备终端命令
   • 常见选项和标志
   • 使用示例

安装

1. 创建虚拟环境：

uv venv

2. 激活虚拟环境：

source .venv/bin/activate

3. 安装依赖：

uv pip install -e .

添加到 Claude

1. 找到 Claude 的桌面配置文件：

~/Library/Application Support/Claude/claude_desktop_config.json

2. 添加终端服务配置：

{
    "mcpServers": {
        "terminal": {
            "command": "/path/to/terminal-mcp-server/.venv/bin/python",
            "args": [
                "/path/to/terminal-mcp-server/src/server.py"
            ]
        }
    }
}

将 /path/to/terminal-mcp-server 替换为克隆此仓库的实际路径。

3. 重启 Claude 以加载新配置。

使用 MCP Inspector 进行测试

你可以使用 MCP Inspector 工具测试 MCP 服务。该工具提供了一个用于与 MCP 服务交互的 Web 界面。

1. 安装 MCP Inspector：

npm install -g @modelcontextprotocol/inspector

2. 在另一个终端中运行 Inspector：

npx @modelcontextprotocol/inspector

这将在本地启动一个 Web 应用，你可以在其中：

• 连接到 MCP 服务
• 测试所有可用工具
• 查看工具响应
• 检查资源
• 调试通信

用法

该服务提供：

1. run_command 工具：

# Safe command execution
result = await run_command("ls -la")
print(result["stdout"])  # Command output
print(result["stderr"])  # Any errors
print(result["return_code"])  # Exit code

2. magical_tool：

# WARNING: Demonstrates unsafe command execution
# Shows how external commands can be executed without proper validation
result = await magical_tool()
print(result["stdout"])  # Executed command output
print(result["stderr"])  # Any errors
print(result["return_code"])  # Command exit code

3. terminal_commands_cheat_sheet 资源：

# Access terminal commands cheat sheet
commands = await terminal_commands_cheat_sheet()
print(commands)  # List of commands with examples

安全影响

magical_tool 演示了一种常见的安全漏洞：用户输入或文件路径未经适当验证就直接用于命令执行。这可能导致：

1. 命令注入
2. 任意文件访问
3. 系统操控

此示例仅用于教育目的，演示了生产系统中不应采用的做法。

开发

1. 克隆仓库
2. 按照上述说明创建并激活虚拟环境
3. 安装依赖
4. 运行服务：

uv run src/server.py

错误处理

• 所有工具都会妥善处理错误
• 命令执行失败时会在 stderr 中返回错误消息
• 资源访问失败时会返回错误消息
• 非零返回码表示命令执行失败

许可证

MIT