Skip to main content
Glama
sichang824

MCP Terminal

by sichang824
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

MCP Terminal

MCP Terminal 是一个基于 MCP（Model Context Protocol）的终端控制服务器，专为与大型语言模型（LLM）和 AI 助手集成而设计。它提供了一个标准化的接口，使 AI 可以执行终端命令并获取输出结果。

English | 中文

演示视频

演示视频

Related MCP server: Terminal MCP Server

特性

  • 使用官方 MCP SDK 实现

  • 支持多种终端控制器：

    • iTerm2 控制器：在 macOS 上使用 iTerm2 的 Python API 提供高级控制

    • AppleScript 控制器：在 macOS 上使用 AppleScript 控制 Terminal 应用

    • Subprocess 控制器：在所有平台上通用的终端控制方式

  • 支持多种服务器模式：

    • STDIO 模式：通过标准输入/输出与客户端通信

    • SSE 模式：通过 Server-Sent Events 提供 HTTP API

  • 提供多种工具：

    • 终端工具：执行命令并获取输出

    • 文件工具：进行文件操作（读写、追加、插入）

  • 自动检测最佳终端控制器

  • 与 Claude Desktop 无缝集成

  • 支持 Docker 部署

安装

先决条件

  • Python 3.8+

  • uv 包管理工具

如果您还没有安装 uv，可以通过以下命令安装：

# 在macOS上使用Homebrew
brew install uv

# 在其他平台上
pip install uv

使用 uv 安装（推荐）

克隆仓库并使用 uv 安装依赖：

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

# 创建虚拟环境并安装基本依赖
uv venv
source .venv/bin/activate  # 在Windows上使用 .venv\Scripts\activate
uv pip install -e .

# 如果需要iTerm2支持 (仅限macOS)
uv pip install -e ".[iterm]"

# 如果需要开发工具（测试、代码格式化等）
uv pip install -e ".[dev]"

注意：如需使用 iTerm2 控制器，必须在 iTerm2 设置中启用 Python API。

打开 iTerm2，依次进入 Preferences → General → Magic，勾选 Enable Python API 选项，如下图所示：

Enable Python API in iTerm2

使用 Makefile 安装

我们提供了 Makefile 来简化常见操作：

# 安装基本依赖
make setup

# 安装iTerm2支持
make setup-iterm

# 安装开发依赖
make setup-dev

使用 Docker 安装

我们提供了 Docker 支持，可以快速部署 MCP Terminal 服务器：

# 构建 Docker 镜像
docker build -t mcp-terminal .

# 运行 Docker 容器（SSE模式，端口8000）
docker run -p 8000:8000 mcp-terminal

或者使用 docker-compose：

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

使用方法

运行 MCP 终端服务器

有多种方式可以启动服务器：

# 使用Python直接运行（默认使用stdio模式和自动检测终端控制器）
python mcp_terminal.py

# 使用Makefile运行（stdio模式）
make run-stdio

# 使用Makefile运行（SSE模式）
make run-sse

# 使用指定控制器
make run-iterm     # 使用iTerm2控制器
make run-applescript  # 使用AppleScript控制器
make run-subprocess   # 使用Subprocess控制器

使用 Docker 运行

使用 Docker 运行 MCP Terminal 服务器（默认使用 SSE 模式和 Subprocess 控制器）：

# 直接运行
docker run -p 8000:8000 mcp-terminal

# 使用自定义端口
docker run -p 9000:8000 mcp-terminal

# 挂载当前目录（可访问本地文件）
docker run -p 8000:8000 -v $(pwd):/workspace mcp-terminal

默认配置：

  • 服务器模式：SSE

  • 主机：0.0.0.0（允许远程连接）

  • 端口：8000

  • 控制器：subprocess（适合容器环境）

您可以通过修改 Dockerfile 或 docker-compose.yml 文件来自定义配置。

在 Claude 或其他 AI 中使用 Docker 容器作为 MCP 服务

您可以将 Docker 容器配置为 MCP 服务，使 Claude 或其他支持 MCP 的 AI 可以直接使用容器化的工具。以下是在 Claude 配置文件中使用 Docker 容器作为 MCP 服务的示例：

{
  "mcp": {
    "servers": {
      "terminal": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "--mount",
          "type=bind,src=${workspaceFolder},dst=/workspace",
          "mcp-terminal",
          "mcp-terminal",
          "--mode",
          "sse",
          "--host",
          "0.0.0.0",
          "--port",
          "8000"
        ]
      }
    }
  }
}

这种配置允许：

  • 通过 Docker 容器隔离工具执行环境

  • 无需在本地安装特定工具即可使用其功能

  • 在不同环境中保持一致的工具版本和配置

  • 使用 ${workspaceFolder} 变量将当前工作目录挂载到容器中

  • 通过 --rm 标志确保容器使用后自动删除，保持环境清洁

您可以根据需要定义多个不同的 MCP 服务容器，每个容器专注于特定的功能。

Claude Desktop 集成配置示例

以下是 Claude Desktop 的配置示例：

{
  "mcpServers": {
    "terminal": {
      "command": "/Users/ann/Workspace/mcp-terminal/.venv/bin/python",
      "args": [
        "/Users/ann/Workspace/mcp-terminal/mcp_terminal.py",
        "--controller",
        "subprocess"
      ]
    }
  }
}

命令行选项

服务器支持多种命令行选项：

python mcp_terminal.py --help

主要选项：

  • --controller 或 -c：指定终端控制器类型（auto, iterm, applescript, subprocess）

  • --mode 或 -m：指定服务器模式（stdio, sse）

  • --host：指定 SSE 模式主机地址

  • --port 或 -p：指定 SSE 模式端口

  • --log-level 或 -l：指定日志级别

与 Claude Desktop 集成

MCP Terminal 可以与 Claude Desktop 无缝集成，为 Claude 提供终端控制能力。

配置步骤

  1. 启动 MCP Terminal 服务器（以 stdio 模式）：

    # 在一个终端窗口中运行
make run-stdio

  2. 配置 Claude Desktop 使用 MCP 服务器：

    打开 Claude Desktop，然后：

    • 点击设置图标（通常在右上角）

    • 导航到"扩展"或"工具"选项卡

    • 启用"自定义工具"功能

    • 添加 MCP Terminal 的配置：

      • 工具名称：Terminal

      • 工具路径：输入 mcp_terminal.py 的完整路径

      • 使用 stdio 模式：勾选

      • 保存配置

  3. 测试集成：

    在与 Claude 的对话中，你现在可以请求 Claude 执行终端命令，例如：

    • "请列出我的主目录下的文件"

    • "检查我当前的 Python 版本"

    • "创建一个新目录并将当前日期写入一个文件"

故障排除

如果集成不正常工作：

  1. 确保 MCP Terminal 服务器正在运行

  2. 检查日志输出以查找错误

  3. 验证 Claude Desktop 的工具配置是否正确

  4. 尝试重启 Claude Desktop 和 MCP Terminal 服务器

API 规范

MCP Terminal 提供以下 MCP 函数：

execute_command

执行终端命令并获取输出结果。

参数：

  • command (string)：要执行的命令

  • wait_for_output (boolean, 可选)：是否等待并返回命令输出，默认为 true

  • timeout (integer, 可选)：等待输出的超时时间（秒），默认为 10

返回：

  • success (boolean)：命令是否成功执行

  • output (string, 可选)：命令的输出结果

  • error (string, 可选)：如果命令失败，返回错误信息

  • return_code (integer, 可选)：命令的返回代码

  • warning (string, 可选)：警告信息

get_terminal_info

获取终端信息。

参数：无

返回：

  • terminal_type (string)：正在使用的终端类型

  • platform (string)：运行平台

file_modify

写入、追加或插入内容到文件。

参数：

  • filepath (string)：文件路径

  • content (string)：要写入的内容

  • mode (string, 可选)：写入模式，可选值为 "overwrite"（覆盖）、"append"（追加）或 "insert"（插入），默认为 "overwrite"

  • position (integer, 可选)：使用 "insert" 模式时的插入位置

  • create_dirs (boolean, 可选)：如果目录不存在，是否创建目录，默认为 true

返回：

  • success (boolean)：操作是否成功

  • error (string, 可选)：如果操作失败，返回错误信息

  • filepath (string)：操作的文件路径

  • details (object, 可选)：额外的操作详情

安全考虑

MCP Terminal 允许执行任意终端命令，这可能带来安全风险。在生产环境中使用时，应该：

  1. 限制服务器只接受来自受信任来源的连接

  2. 考虑实现命令白名单或黑名单

  3. 定期审计执行的命令

  4. 在专用账户下运行服务器，限制其权限

开发

目录结构

mcp-terminal/
├── mcp_terminal.py            # 入口点脚本
├── pyproject.toml             # 项目配置和依赖
├── README.md                  # 项目文档
├── Makefile                   # 构建和运行命令
├── Dockerfile                 # Docker 构建配置
├── docker-compose.yml         # Docker Compose 配置
├── src/
│   ├── __init__.py
│   └── mcp_terminal/
│       ├── __init__.py
│       ├── server.py          # 主服务器实现
│       ├── controllers/
│       │   ├── __init__.py    # 控制器工厂和导入
│       │   ├── base.py        # 基础控制器接口
│       │   ├── subprocess.py  # 通用子进程控制器
│       │   ├── applescript.py # AppleScript控制器
│       │   └── iterm.py       # iTerm2 API控制器
│       └── tools/
│           ├── __init__.py
│           ├── terminal.py    # 终端操作工具
│           └── file.py        # 文件操作工具
└── tests/                     # 测试目录
    ├── __init__.py
    └── test_subprocess_controller.py

运行测试

# 使用pytest运行所有测试
make test

# 或者直接使用pytest
pytest tests/

代码格式化

# 检查代码格式
make lint

# 自动格式化代码
make format

贡献

欢迎贡献！请遵循以下步骤：

  1. Fork 仓库

  2. 创建功能分支 (git checkout -b feature/amazing-feature)

  3. 提交更改 (git commit -m 'Add some amazing feature')

  4. 推送到分支 (git push origin feature/amazing-feature)

  5. 提交 Pull Request

许可证

此项目采用 MIT 许可证 - 详情见LICENSE文件。

Available Tools

3 tools
execute_commandC

Executes a terminal command

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYes
wait_for_outputNo
timeoutNo

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden but only states the action without disclosing behavioral traits. It doesn't mention permissions needed, side effects (e.g., file changes, system impacts), error handling, or output format, which is critical for a command execution tool.

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

Conciseness5/5

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

The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, though this brevity contributes to underspecification rather than clarity.

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?

For a 3-parameter tool with no annotations, no output schema, and 0% schema coverage, the description is incomplete. It lacks essential details about execution context, safety, and results, making it inadequate for informed tool selection and invocation.

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

Parameters1/5

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

Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'command' should contain, how 'wait_for_output' affects behavior, or what 'timeout' units are (seconds?), leaving all three parameters undocumented.

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

Purpose3/5

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

The description 'Executes a terminal command' states the basic action (verb+resource) but is vague about scope and lacks differentiation from siblings like 'get_terminal_info'. It doesn't specify what kind of commands or execution environment, making it minimally adequate but unclear.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like 'file_modify' or 'get_terminal_info'. The description implies execution but doesn't mention prerequisites, safety considerations, or typical use cases, leaving the agent with no contextual direction.

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

file_modifyC

Writes content to a file

ParametersJSON Schema
NameRequiredDescriptionDefault
filepathYes
contentYes
modeNooverwrite
positionNo
create_dirsNo

TDQS

C2.4/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. 'Writes content to a file' indicates a mutation operation but fails to detail critical aspects such as permissions required, error handling (e.g., if the file doesn't exist), side effects, or response format. It doesn't contradict annotations (none exist), but offers minimal behavioral insight beyond the basic action.

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

Conciseness5/5

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

The description is extremely concise with 'Writes content to a file', a single sentence that front-loads the core action without unnecessary words. It's appropriately sized for the basic purpose, though this brevity contributes to gaps in other dimensions.

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 (5 parameters, mutation tool, no annotations, no output schema), the description is incomplete. It doesn't explain parameter roles, behavioral traits, or return values, leaving the agent with insufficient information to use the tool effectively. The conciseness comes at the cost of essential details needed for proper invocation.

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

Parameters1/5

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

Schema description coverage is 0%, meaning parameters like 'filepath', 'content', 'mode', 'position', and 'create_dirs' are undocumented in the schema. The description adds no meaning beyond the basic action, failing to explain what these parameters do, their formats, or how they affect the write operation. For a tool with 5 parameters, this is a significant gap.

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

Purpose3/5

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

The description 'Writes content to a file' clearly states the verb ('writes') and resource ('a file'), making the basic purpose understandable. However, it lacks specificity about what kind of writing (e.g., overwriting, appending) and doesn't differentiate from potential sibling tools like 'execute_command' or 'get_terminal_info', which are unrelated to file operations. It's not tautological but remains somewhat vague.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. There are no explicit instructions on scenarios for application, prerequisites, or comparisons with sibling tools (e.g., 'execute_command' for command execution vs. file writing). Usage is implied by the action but lacks contextual direction.

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

get_terminal_infoC

Gets terminal information

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Gets terminal information', implying a read-only operation, but doesn't specify what information is returned (e.g., format, structure), whether it requires permissions, or if there are rate limits. The description is too vague to provide meaningful behavioral context beyond the basic action.

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

Conciseness3/5

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

The description 'Gets terminal information' is concise with a single sentence, but it's under-specified rather than efficiently informative. It lacks front-loaded detail that could clarify the tool's purpose, making it too brief to be truly helpful. While not verbose, it fails to earn its place by providing sufficient value.

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 tool's simplicity (0 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain what 'terminal information' entails, the return format, or any behavioral aspects. For a tool with no structured data to rely on, the description should provide more context to be fully usable by an agent.

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

Parameters4/5

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

The tool has 0 parameters, and the input schema has 100% description coverage (though empty). With no parameters to document, the description doesn't need to add parameter semantics. A baseline score of 4 is appropriate as the schema fully covers the parameterless nature, and the description doesn't introduce confusion.

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

Purpose2/5

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

The description 'Gets terminal information' is a tautology that essentially restates the tool name 'get_terminal_info'. It provides a verb ('Gets') and resource ('terminal information'), but lacks specificity about what information is retrieved (e.g., terminal type, dimensions, capabilities) and doesn't differentiate from sibling tools like 'execute_command' or 'file_modify'. This makes it vague and minimally informative.

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

Usage Guidelines1/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or exclusions, and fails to distinguish it from sibling tools such as 'execute_command' (for running commands) or 'file_modify' (for file operations). This absence of usage instructions leaves the agent without direction.

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. Dates show when Glama detected each change.

  1. 3 tool updates
    • First observedexecute_command
    • First observedfile_modify
    • First observedget_terminal_info
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.8/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: execute_command runs terminal commands, file_modify writes to files, and get_terminal_info retrieves terminal metadata. An agent can easily differentiate between executing commands, modifying files, and gathering system information without confusion.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (execute_command, file_modify, get_terminal_info), using snake_case throughout. The naming is predictable and readable, with no deviations in style or convention across the set.

Tool Count3/5

With only 3 tools, the set feels thin for a terminal server, lacking operations like reading files, navigating directories, or managing processes. While the tools are well-defined, the count is borderline low for the apparent scope of terminal interactions, potentially limiting agent workflows.

Completeness2/5

There are significant gaps in the tool surface for terminal operations. Missing are essential functions like reading files, listing directories, checking command history, or handling environment variables. This incomplete coverage will likely cause agent failures when attempting common terminal tasks beyond basic command execution and file writing.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sichang824/mcp-terminal'

If you have feedback or need assistance with the MCP directory API, please join our Discord server