项目简介

Terminal MCP Server 是一个实现了 Model Context Protocol (MCP) 的服务器，它提供了一个 'execute_command' 工具，允许连接到该服务器的 LLM 客户端（如 Claude、Roo Code、Cline 等）执行本地或远程主机的终端命令。通过会话管理和多种连接方式（stdio, SSE），为 LLM 应用提供安全、可扩展的系统操作能力。

主要功能点

本地命令执行: 允许 LLM 客户端在运行 MCP 服务器的本地机器上执行命令。
远程命令执行: 支持通过 SSH 在远程主机上执行命令，扩展了 LLM 的操作范围。
会话持久化: 支持会话保持，在一段时间内（默认 20 分钟）重复使用相同的终端环境，便于执行需要连续环境的操作。
环境变量: 允许为执行的命令设置自定义环境变量，提供更灵活的命令执行环境。
多种连接方式: 支持通过标准输入输出 (stdio) 和服务器发送事件 (SSE) 两种方式连接服务器，满足不同场景的需求。

安装步骤

克隆仓库

git clone https://github.com/weidwonder/terminal-mcp-server.git
cd terminal-mcp-server

安装依赖
```
npm install
```
构建项目
```
npm run build
```

服务器配置

MCP 客户端需要配置 MCP 服务器的连接信息才能使用 Terminal MCP Server。以下是针对不同连接方式的配置示例，以 JSON 格式提供。

1. Stdio 模式 (本地连接)

适用于 MCP 客户端和 Terminal MCP Server 运行在同一台机器上的场景。客户端需要配置服务器的启动命令和参数。

{
  "mcpServers": {
    "terminal-mcp": {  // 服务器名称，客户端自定义
      "command": "node", // 启动命令，这里使用 node
      "args": ["/path/to/terminal-mcp-server/build/index.js"], // 命令参数，指向构建后的服务器入口文件
      "env": {} // 环境变量，可选
    }
  }
}

配置参数说明:

'"terminal-mcp"': MCP 服务器的名称，可以自定义，在客户端中用于标识和选择该服务器。
'"command"': 启动 MCP 服务器的命令，通常为 'node' 或服务器的可执行文件路径。
'"args"': 启动命令的参数数组，指向 'terminal-mcp-server' 项目构建后的入口文件 'build/index.js' 的路径。请务必将 '/path/to/terminal-mcp-server' 替换为实际的项目路径。
'"env"': 可选的环境变量对象，可以设置服务器运行时的环境变量。

2. SSE 模式 (远程连接)

适用于 MCP 客户端和 Terminal MCP Server 运行在不同机器上的场景。客户端需要配置服务器的 URL 地址。

{
  "mcpServers": {
    "terminal-mcp-sse": { // 服务器名称，客户端自定义
      "url": "http://localhost:8080/sse", // SSE 连接 URL，默认为 http://localhost:8080/sse
      "headers": {} // HTTP 请求头，可选
    }
  }
}

配置参数说明:

'"terminal-mcp-sse"': MCP 服务器的名称，可以自定义。
'"url"': Terminal MCP Server 的 SSE 连接 URL。请根据服务器实际启动参数 (如 '--port', '--endpoint', '--host') 修改 'url' 中的地址、端口和路径。 默认配置下，如果服务器运行在本地 8080 端口，则 URL 为 'http://localhost:8080/sse'。
'"headers"': 可选的 HTTP 请求头，用于 SSE 连接。

服务器 SSE 模式启动命令示例:

node build/index.js --sse --port 3000 --endpoint /mcp --host 0.0.0.0

此命令将启动 SSE 服务器，监听端口 '3000'，端点路径为 '/mcp'，并绑定到所有网络接口 ('0.0.0.0')。客户端配置的 '"url"' 应相应地修改为 'http://服务器IP地址:3000/mcp'。

基本使用方法

启动服务器: 根据需要选择 stdio 模式或 SSE 模式启动 Terminal MCP Server。
- stdio 模式: 'npm start' 或 'node build/index.js'
- SSE 模式: 'npm run start:sse' 或 'node build/index.js --sse' (可根据需要添加 '--port', '--endpoint', '--host' 参数)
配置 MCP 客户端: 在 LLM 客户端（如 Claude、Roo Code、Cline）的 MCP 服务器配置中，添加上述 JSON 配置信息，选择合适的连接模式 (stdio 或 SSE)，并确保配置中的路径和 URL 与实际服务器运行情况一致。
在 LLM 中使用 'execute_command' 工具: 配置完成后，在支持 MCP 协议的 LLM 应用中，即可调用 'execute_command' 工具执行命令。工具参数包括 'command' (必填，要执行的命令), 'host' (可选，远程主机地址), 'username' (可选，SSH 用户名，当指定 'host' 时必填), 'session' (可选，会话名称), 'env' (可选，环境变量)。

示例 (JSON 格式，用于 LLM 客户端调用工具):

本地执行命令:

{
  "tool_calls": [
    {
      "id": "tool_call_123",
      "type": "function",
      "function": {
        "name": "execute_command",
        "arguments": "{\"command\": \"ls -la\", \"session\": \"my-local-session\"}"
      }
    }
  ]
}

远程执行命令:

{
  "tool_calls": [
    {
      "id": "tool_call_456",
      "type": "function",
      "function": {
        "name": "execute_command",
        "arguments": "{\"host\": \"example.com\", \"username\": \"user\", \"command\": \"df -h\", \"session\": \"my-remote-session\"}"
      }
    }
  ]
}

请注意，远程命令执行需要预先配置好 SSH 密钥认证。

关键词