Mcpターミナル

作成者：

sichang824•Jun 25, 2025

MCP Terminal は、MCP（Model Context Protocol）に基づいたターミナル制御サーバーであり、大規模言語モデル（LLM）や AI アシスタントとの統合のために特別に設計されています。これにより、AI がターミナルコマンドを実行し、出力結果を取得できる標準化されたインターフェースを提供します。

Developer Tools

概要

MCPターミナルとは？

MCPターミナルは、モデルコンテキストプロトコル（MCP）に基づいたターミナル制御サーバーであり、大規模言語モデル（LLM）やAIアシスタントとの統合のために特別に設計されています。これは、AIシステムがターミナルコマンドを実行し、出力結果をシームレスに取得できる標準化されたインターフェースを提供します。この機能は、コマンドラインインタラクションを必要とするAI機能でアプリケーションを強化したい開発者にとって重要です。

MCPターミナルの特徴

標準化されたインターフェース：MCPターミナルは、AIシステムがターミナルコマンドと対話するための一貫した使いやすいインターフェースを提供します。
AIとの統合：大規模言語モデルと連携するように特別に設計されており、AI分野の開発者にとって理想的な選択肢です。
コマンド実行：ターミナルはさまざまなコマンドの実行を可能にし、AIがコマンドラインアクセスを必要とするタスクを実行できるようにします。
出力取得：コマンドを実行した後、MCPターミナルは出力を取得し返します。これにより、AIシステムはさらなる処理や意思決定に利用できます。
公開リポジトリ：MCPターミナルは公開リポジトリとして利用可能で、開発者がプロジェクトに貢献したり、フォークしたり、強化したりできます。

MCPターミナルの使い方

インストール：GitHubからMCPターミナルのリポジトリをクローンして、ローカルマシンにインストールします。
```
git clone https://github.com/sichang824/mcp-terminal.git
```
セットアップ：リポジトリ内の指示に従って、MCPターミナルを実行するために必要な環境と依存関係を設定します。
統合：APIを利用してコマンドを送信し、出力を受け取ることで、AIアプリケーションにMCPターミナルを統合します。
コマンド実行：提供されたメソッドを使用して、AIモデルを通じてターミナルコマンドを実行し、応答を適切に処理します。
貢献：改善点や追加機能がある場合は、リポジトリをフォークし、プルリクエストを提出することを検討してください。

よくある質問

Q1: MCPターミナルはどのプログラミング言語をサポートしていますか？

A1: MCPターミナルは言語に依存しないように設計されており、HTTPリクエストを送信できる任意のプログラミング言語と統合できます。

Q2: MCPターミナルを商業目的で使用できますか？

A2: はい、MCPターミナルはMITライセンスの下でライセンスされており、商業利用が許可されています。

Q3: MCPターミナルプロジェクトにどのように貢献できますか？

A3: リポジトリをフォークし、変更を加え、プルリクエストを提出することで貢献できます。リポジトリに記載されている貢献ガイドラインに従うことを確認してください。

Q4: MCPターミナルのドキュメントはありますか？

A4: はい、セットアップ手順、APIの使用法、例を含む詳細なドキュメントがリポジトリにあります。

Q5: MCPターミナルを実行するためのシステム要件は何ですか？

A5: MCPターミナルは、必要な依存関係をサポートする任意のシステムで実行でき、通常は最新のオペレーティングシステムと互換性のあるランタイム環境が必要です。

詳細

MCP Terminal

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

English | 中文

</div>

演示视频

特性

使用官方 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 选项，如下图所示：

使用 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 提供终端控制能力。

配置步骤

启动 MCP Terminal 服务器（以 stdio 模式）：
```
# 在一个终端窗口中运行
make run-stdio
```
配置 Claude Desktop 使用 MCP 服务器：

打开 Claude Desktop，然后：
- 点击设置图标（通常在右上角）
- 导航到"扩展"或"工具"选项卡
- 启用"自定义工具"功能
- 添加 MCP Terminal 的配置：
  - 工具名称：Terminal
  - 工具路径：输入 mcp_terminal.py 的完整路径
  - 使用 stdio 模式：勾选
  - 保存配置
测试集成：

在与 Claude 的对话中，你现在可以请求 Claude 执行终端命令，例如：
- "请列出我的主目录下的文件"
- "检查我当前的 Python 版本"
- "创建一个新目录并将当前日期写入一个文件"

故障排除

如果集成不正常工作：

确保 MCP Terminal 服务器正在运行
检查日志输出以查找错误
验证 Claude Desktop 的工具配置是否正确
尝试重启 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 允许执行任意终端命令，这可能带来安全风险。在生产环境中使用时，应该：

限制服务器只接受来自受信任来源的连接
考虑实现命令白名单或黑名单
定期审计执行的命令
在专用账户下运行服务器，限制其权限

开发

目录结构

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

贡献

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

Fork 仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
提交 Pull Request

许可证

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

サーバー設定

{
  "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"
        ]
      }
    }
  }
}

プロジェクト情報

著者

sichang824