Skip to main content
Glama
Terminal Controller for MCP

Terminal Controller for MCP

by GongRzhe

MCP 终端控制器

模型上下文协议 (MCP) 服务器,通过标准化接口实现安全终端命令执行、目录导航和文件系统操作。

铁匠徽章

特征

  • 命令执行:运行具有超时控制和全面输出捕获的终端命令

  • 目录管理:以直观的格式导航和列出目录内容

  • 安全措施:内置安全措施,防止危险命令和操作

  • 命令历史记录:跟踪并显示最近的命令执行

  • 跨平台支持:适用于 Windows 和基于 UNIX 的系统

  • 文件操作:以行级精度读取、写入、更新、插入和删除文件内容

Related MCP server: MCP Server

安装

通过 Smithery 安装

要通过Smithery自动安装 Claude Desktop 的终端控制器:

npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claude

先决条件

  • Python 3.11+

  • 与 MCP 兼容的客户端(例如 Claude Desktop)

  • 安装 UV/UVX(可选,用于 UVX 方法)

方法 1:PyPI 安装(推荐)

直接从 PyPI 安装包:

pip install terminal-controller

或者如果您更喜欢使用 UV:

uv pip install terminal-controller

方法 2:从源

如果您希望从源代码安装:

  1. 克隆此存储库:

    git clone https://github.com/GongRzhe/terminal-controller-mcp.git
    cd terminal-controller-mcp
  2. 运行安装脚本:

    python setup_mcp.py

客户端配置

克劳德桌面

有两种方法可以配置 Claude Desktop 使用终端控制器:

选项 1:使用 UVX(推荐)

将其添加到您的 Claude Desktop 配置文件中:

"terminal-controller": {
  "command": "uvx",
  "args": ["terminal_controller"]
}

选项 2:直接使用 Python

"terminal-controller": {
  "command": "python",
  "args": ["-m", "terminal_controller"]
}

配置路径因操作系统而异:

  • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows : %APPDATA%\Claude\claude_desktop_config.json

光标

对于 Cursor,使用与 Claude Desktop 类似的配置设置。

其他 MCP 客户端

对于其他客户端,请参阅其文档以了解如何配置外部 MCP 服务器。

用法

配置完成后,您可以使用自然语言通过 MCP 客户端与您的终端进行交互:

  • “在当前目录中运行命令ls -la ”

  • “导航到我的文档文件夹”

  • “显示我的下载目录的内容”

  • “显示我最近的命令历史记录”

  • “读取config.json的内容”

  • “使用‘print(“Hello World”)’更新我的 script.py 文件中的第 5 行”

  • “从日志文件中删除第 10 至 15 行”

  • “在我的文本文件的开头插入一个新行”

API 参考

终端控制器公开以下 MCP 工具:

execute_command

执行终端命令并返回其结果。

参数:

  • command :要执行的命令行命令

  • timeout :命令超时(秒)(默认值:30)

返回:

  • 命令执行的输出,包括 stdout、stderr 和执行状态

get_command_history

获取最近的命令执行历史记录。

参数:

  • count :返回的最近命令数(默认值:10)

返回:

  • 格式化的命令历史记录

get_current_directory

获取当前工作目录。

返回:

  • 当前工作目录的路径

change_directory

更改当前工作目录。

参数:

  • path :切换到的目录路径

返回:

  • 操作结果信息

list_directory

列出指定目录中的文件和子目录。

参数:

  • path :列出内容的目录路径(默认值:当前目录)

返回:

  • 目录内容列表,使用目录和文件的图标格式化

write_file

使用覆盖或附加选项将内容写入文件。

参数:

  • path :文件路径

  • content :要写的内容

  • mode :写入模式('覆盖'或'附加',默认值:'覆盖')

返回:

  • 操作结果信息包括写入成功的验证

read_file

从文件中读取内容,并可选择行。

参数:

  • path :文件路径

  • start_row :读取的起始行(从 0 开始,可选)

  • end_row :读取的结束行(从 0 开始,包含 0,可选)

返回:

  • 文件内容或选定的行

insert_file_content

在文件的特定行插入内容。

参数:

  • path :文件路径

  • content :要插入的内容

  • row :要插入的行号(从 0 开始,可选)

  • rows :要插入的行号列表(从 0 开始,可选)

返回:

  • 操作结果信息

delete_file_content

从文件中删除特定行的内容。

参数:

  • path :文件路径

  • row :要删除的行号(从 0 开始,可选)

  • rows :要删除的行号列表(从 0 开始,可选)

返回:

  • 操作结果信息

update_file_content

更新文件中特定行的内容。

参数:

  • path :文件路径

  • content :放置在指定行的新内容

  • row :要更新的行号(从 0 开始,可选)

  • rows :要更新的行号列表(从 0 开始,可选)

返回:

  • 操作结果信息

安全注意事项

终端控制器实施了多项安全措施:

  • 超时控制以防止长时间运行的命令

  • 危险命令黑名单(rm -rf /、format、mkfs)

  • 正确的错误处理和命令执行的隔离

  • 仅访问明确授予的命令和目录

限制

  • 只有在超时时间内完成的命令才会返回结果

  • 默认情况下,服务器具有与运行它的用户相同的文件系统权限

  • 由于终端界面的非交互特性,某些交互式命令可能无法按预期工作

故障排除

如果您遇到问题:

  1. 检查你的 Python 版本是否为 3.11 或更高版本

  2. 验证您的 Claude Desktop 配置是否正确

  3. 尝试直接运行终端控制器来检查错误:

    python -m terminal_controller
  4. 对于与 UVX 相关的问题,请尝试:

    uvx terminal_controller
  5. 检查 MCP 客户端日志中的连接错误

贡献

欢迎贡献代码!欢迎提交 Pull 请求。

执照

麻省理工学院

Available Tools

10 tools
change_directoryC
Change current working directory

Args:
    path: Directory path to switch to

Returns:
    Operation result information

Inputs: path (required).

delete_file_contentA
Delete content at specific row(s) from a file

Args:
    path: Path to the file
    row: Row number to delete (0-based, optional)
    rows: List of row numbers to delete (0-based, optional)
    substring: If provided, only delete this substring within the specified row(s), not the entire row (optional)

Returns:
    Operation result information

Inputs: path (required), row, rows, substring.

execute_commandB
Execute terminal command and return results

Args:
    command: Command line command to execute
    timeout: Command timeout in seconds, default is 30 seconds

Returns:
    Output of the command execution

Inputs: command (required), timeout.

get_command_historyB
Get recent command execution history

Args:
    count: Number of recent commands to return

Returns:
    Formatted command history record

Inputs: count.

get_current_directoryA
Get current working directory

Returns:
    Path of current working directory

Inputs: no named parameters.

insert_file_contentB
Insert content at specific row(s) in a file

Args:
    path: Path to the file
    content: Content to insert (string or JSON object)
    row: Row number to insert at (0-based, optional)
    rows: List of row numbers to insert at (0-based, optional)

Returns:
    Operation result information

Inputs: path (required), content (required), row, rows.

list_directoryA
List files and subdirectories in the specified directory

Args:
    path: Directory path to list contents, default is current directory

Returns:
    List of directory contents

Inputs: path.

read_fileA
Read content from a file with optional row selection

Args:
    path: Path to the file
    start_row: Starting row to read from (0-based, optional)
    end_row: Ending row to read to (0-based, inclusive, optional)
    as_json: If True, attempt to parse file content as JSON (optional)

Returns:
    File content or selected lines, optionally parsed as JSON

Inputs: path (required), start_row, end_row, as_json.

update_file_contentA
Update content at specific row(s) in a file

Args:
    path: Path to the file
    content: New content to place at the specified row(s)
    row: Row number to update (0-based, optional)
    rows: List of row numbers to update (0-based, optional)
    substring: If provided, only replace this substring within the specified row(s), not the entire row

Returns:
    Operation result information

Inputs: path (required), content (required), row, rows, +1 more.

write_fileB
Write content to a file

Args:
    path: Path to the file
    content: Content to write (string or JSON object)
    mode: Write mode ('overwrite' or 'append')

Returns:
    Operation result information

Inputs: path (required), content (required), mode.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: directory change/get/list, file read/write/insert/update/delete, command execution, and history retrieval. No overlapping functionality.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case, using imperative verbs like change, delete, execute, get, insert, list, read, update, write. The naming is predictable and uniform.

    Tool Count5/5

    With 10 tools, the set is well-scoped for a terminal controller, providing essential file and directory operations plus command execution without oversaturation.

    Completeness4/5

    The surface covers core file CRUD (create via write, read, update, delete) and directory navigation, plus command execution and history. Missing directory creation/deletion and file copy/move, but these are minor gaps for typical agent workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server allowing LLMs to execute commands on Windows terminals, including local shells (cmd, PowerShell, bash) and remote SSH connections with a 3-level security model.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.
      13
      158 npm
      6
      MIT