Terminal MCP 服务器

中文文档

Terminal MCP 服务器是一个模型上下文协议 (MCP) 服务器，允许在本地或远程主机上执行命令。它为 AI 模型和其他应用程序提供了一个简单而强大的接口，可以通过 SSH 在本地计算机或远程主机上执行系统命令。

特性

• 本地命令执行: 直接在本地机器上执行命令
• 远程命令执行: 通过 SSH 在远程主机上执行命令
• 会话持久性: 支持持久会话，在指定时间内（默认为 20 分钟）重用相同的终端环境
• 环境变量: 为命令设置自定义环境变量
• 多种连接方式: 通过 stdio 或 SSE (Server-Sent Events) 连接

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 terminal-mcp-server：

npx -y @smithery/cli install @weidwonder/terminal-mcp-server --client claude

手动安装

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

# 安装依赖
npm install

# 构建项目
npm run build

使用

启动服务器

# 使用 stdio 启动服务器（默认模式）
npm start

# 或者直接运行构建后的文件
node build/index.js

以 SSE 模式启动服务器

SSE (Server-Sent Events) 模式允许您通过 HTTP 远程连接到服务器。

# 以 SSE 模式启动服务器
npm run start:sse

# 或者使用 SSE 标志直接运行构建后的文件
node build/index.js --sse

您可以使用以下命令行选项自定义 SSE 服务器：

选项	描述	默认值
--port 或 -p	监听的端口	8080
--endpoint 或 -e	端点路径	/sse
--host 或 -h	绑定的主机	localhost

使用自定义选项的示例：

# 在端口 3000 上启动 SSE 服务器，端点为 /mcp，并绑定到所有接口
node build/index.js --sse --port 3000 --endpoint /mcp --host 0.0.0.0

这将启动服务器并监听 http://0.0.0.0:3000/mcp 上的 SSE 连接。

使用 MCP Inspector 测试

# 启动 MCP Inspector 工具
npm run inspector

execute_command 工具

execute_command 工具是 Terminal MCP Server 提供的核心功能，用于在本地或远程主机上执行命令。

参数

参数	类型	是否必需	描述
command	string	是	要执行的命令
host	string	否	要连接的远程主机。如果未提供，则命令将在本地执行
username	string	当指定 host 时必需	SSH 连接的用户名
session	string	否	会话名称，默认为 "default"。相同的会话名称将在 20 分钟内重用相同的终端环境
env	object	否	环境变量，默认为空对象

示例

在本地执行命令

{
  "command": "ls -la",
  "session": "my-local-session",
  "env": {
    "NODE_ENV": "development"
  }
}

在远程主机上执行命令

{
  "host": "example.com",
  "username": "user",
  "command": "ls -la",
  "session": "my-remote-session",
  "env": {
    "NODE_ENV": "production"
  }
}

使用 AI 助手配置

使用 Roo Code 配置

1. 打开 VSCode 并安装 Roo Code 扩展
2. 打开 Roo Code 设置文件：~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
3. 添加以下配置：

对于 stdio 模式（本地连接）

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

对于 SSE 模式（远程连接）

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

如果已自定义，请将 localhost:8080/sse 替换为您的实际服务器地址、端口和端点。

使用 Cline 配置

1. 打开 Cline 设置文件：~/.cline/config.json
2. 添加以下配置：

对于 stdio 模式（本地连接）

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

对于 SSE 模式（远程连接）

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

使用 Claude Desktop 配置

1. 打开 Claude Desktop 设置文件：~/Library/Application Support/Claude/claude_desktop_config.json
2. 添加以下配置：

对于 stdio 模式（本地连接）

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

对于 SSE 模式（远程连接）

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

最佳实践

命令执行

• 在运行命令之前，最好确定系统类型（Mac、Linux 等）
• 使用完整路径以避免与路径相关的问题
• 对于需要维护环境的命令序列，请使用 && 连接多个命令
• 对于长时间运行的命令，请考虑使用 nohup 或 screen/tmux

SSH 连接

• 确保已设置基于 SSH 密钥的身份验证
• 如果连接失败，请检查密钥文件是否存在（默认路径：~/.ssh/id_rsa）
• 确保 SSH 服务在远程主机上运行

会话管理

• 使用会话参数来维护相关命令之间的环境
• 对于需要特定环境的操作，请使用相同的会话名称
• 请注意，会话将在不活动 20 分钟后自动关闭

错误处理

• 命令执行结果包括 stdout 和 stderr
• 检查 stderr 以确定命令是否成功执行
• 对于复杂的操作，添加验证步骤以确保成功

重要提示

• 对于远程命令执行，必须提前设置基于 SSH 密钥的身份验证
• 对于本地命令执行，命令将在启动服务器的用户的上下文中运行
• 会话超时时间为 20 分钟，之后连接将自动关闭