Skip to main content
Glama
enesjakozh
weidwonder

Terminal MCP Server

by weidwonder
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

终端 MCP 服务器

铁匠徽章

中文詳細

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

特征

  • 本地命令执行：直接在本地机器上执行命令

  • 远程命令执行：通过 SSH 在远程主机上执行命令

  • 会话持久性：支持在指定时间内重复使用相同终端环境的持久会话（默认 20 分钟）

  • 环境变量：为命令设置自定义环境变量

  • 多种连接方式：通过 stdio 或 SSE（服务器发送事件）连接

Related MCP server: mcp-remote-ssh

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装终端 mcp 服务器：

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

手动安装

# Clone the repository
git clone https://github.com/weidwonder/terminal-mcp-server.git
cd terminal-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

用法

启动服务器

# Start the server using stdio (default mode)
npm start

# Or run the built file directly
node build/index.js

以 SSE 模式启动服务器

SSE（服务器发送事件）模式允许您通过 HTTP 远程连接到服务器。

# Start the server in SSE mode
npm run start:sse

# Or run the built file directly with SSE flag
node build/index.js --sse

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

选项

描述

默认

--port或-p

监听的端口

8080

--endpoint或-e

端点路径

/sse

--host或-h

绑定到的主机

本地主机

自定义选项的示例：

# Start SSE server on port 3000, endpoint /mcp, and bind to all interfaces
node build/index.js --sse --port 3000 --endpoint /mcp --host 0.0.0.0

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

使用 MCP Inspector 进行测试

# Start the MCP Inspector tool
npm run inspector

execut_command工具

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

参数

范围

类型

必需的

描述

命令

细绳

是的

要执行的命令

主持人

细绳

不

要连接的远程主机。如果未提供，则命令将在本地执行。

用户名

细绳

指定主机时必填

SSH 连接的用户名

会议

细绳

不

会话名称，默认为“default”。相同的会话名称将重复使用相同的终端环境 20 分钟

环境

目的

不

环境变量，默认为空对象

示例

本地执行命令

{
  "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 代码进行配置

  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 服务

会话管理

  • 使用 session 参数来维护相关命令之间的环境

  • 对于需要特定环境的操作，使用相同的会话名称

  • 请注意，会话将在 20 分钟不活动后自动关闭

错误处理

  • 命令执行结果包括stdout和stderr

  • 检查 stderr 以确定命令是否执行成功

  • 对于复杂的操作，添加验证步骤以确保成功

重要提示

  • 对于远程命令执行，必须提前设置基于 SSH 密钥的身份验证

  • 对于本地命令执行，命令将在启动服务器的用户上下文中运行

  • 会话超时为20分钟，超过20分钟后连接将自动关闭

Available Tools

1 tool
execute_commandB

Execute commands on remote hosts or locally (This tool can be used for both remote hosts and the current machine)

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesCommand to execute. Before running commands, it's best to determine the system type (Mac, Linux, etc.)
envNoEnvironment variables
hostNoHost to connect to (optional, if not provided the command will be executed locally)
sessionNoSession name, defaults to 'default'. The same session name will reuse the same terminal environment for 20 minutes, which is useful for operations requiring specific environments like conda.default
usernameNoUsername for SSH connection (required when host is specified)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that commands can be executed remotely or locally and hints at session reuse for 20 minutes, but it lacks critical details such as security implications, error handling, output format, or potential side effects. This leaves significant gaps for a tool that executes arbitrary commands.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core functionality. It avoids unnecessary details and stays focused on the tool's scope, though it could be slightly more structured by explicitly separating remote and local use cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of executing commands (which can have security and system impacts), the lack of annotations, and no output schema, the description is insufficient. It fails to address critical aspects like return values, error conditions, or safety warnings, making it incomplete for informed tool usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the baseline is 3. The description does not add any meaningful parameter semantics beyond what is already documented in the schema, such as explaining the 'command' parameter's system dependencies or the 'session' parameter's environmental implications in more depth.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as executing commands on remote hosts or locally, specifying both the verb ('execute') and the resource ('commands'). It distinguishes between remote and local execution contexts. However, without sibling tools, it cannot demonstrate differentiation from alternatives, preventing a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning both remote and local contexts, but it does not provide explicit guidance on when to choose one over the other or any prerequisites. For example, it notes host is optional for local execution but does not clarify when remote execution is preferable or what conditions might affect it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedexecute_command
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The tool 'execute_command' has a clear, singular purpose that cannot be confused with any other tool in the set.

Naming Consistency5/5

Since there is only one tool, naming consistency is inherently perfect. The tool name 'execute_command' follows a standard verb_noun pattern, and there are no other tools to cause inconsistency.

Tool Count2/5

A single tool for a terminal server is too few for the apparent scope, as terminal operations typically involve multiple commands and actions. This minimal set may cause agents to struggle with complex tasks that require more granular control.

Completeness1/5

The tool surface is severely incomplete for a terminal server domain. It lacks essential operations such as listing files, navigating directories, managing processes, or handling input/output streams, making it inadequate for typical terminal workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Simple SSH MCP Server

    bhayanak
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI assistants full SSH/SFTP remote operations — session management, command execution, interactive shells, file transfers, port forwarding, and system diagnostics.
    2
    MIT

  • mcp-remote-ssh

    faizbawa
    A
    license
    A
    quality
    A
    maintenance
    MCP server giving AI agents full SSH access with persistent sessions, structured command output, SFTP file transfer, and port forwarding.
    18
    11
    MIT

  • ssh-mcp

    slepp
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.
    17
    169 PyPI
    24
    MIT

  • SSH MCP Server

    avranju
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI agents SSH capabilities to execute commands, transfer files, and inspect remote systems through a preconfigured host list.
    41 npm
    MIT

Appeared in Searches