Mcp Terminal
MCP Terminal è un server di controllo terminale basato su MCP (Model Context Protocol), progettato specificamente per l'integrazione con modelli di linguaggio di grandi dimensioni (LLM) e assistenti AI. Fornisce un'interfaccia standardizzata che consente all'AI di eseguire comandi terminali e ottenere risultati di output.
Panoramica
Cos'è MCP Terminal?
MCP Terminal è un server di controllo del terminale basato sul Protocollo di Contesto del Modello (MCP), progettato specificamente per l'integrazione con modelli di linguaggio di grandi dimensioni (LLM) e assistenti AI. Fornisce un'interfaccia standardizzata che consente ai sistemi AI di eseguire comandi del terminale e recuperare i risultati in modo fluido. Questa funzionalità è cruciale per gli sviluppatori che desiderano migliorare le proprie applicazioni con capacità AI che richiedono interazioni da riga di comando.
Caratteristiche di MCP Terminal
- Interfaccia Standardizzata: MCP Terminal offre un'interfaccia coerente e facile da usare per i sistemi AI per interagire con i comandi del terminale.
- Integrazione con AI: È progettato specificamente per lavorare con modelli di linguaggio di grandi dimensioni, rendendolo una scelta ideale per gli sviluppatori nel campo dell'AI.
- Esecuzione di Comandi: Il terminale consente l'esecuzione di vari comandi, permettendo all'AI di svolgere compiti che richiedono accesso da riga di comando.
- Recupero dell'Output: Dopo l'esecuzione dei comandi, MCP Terminal recupera e restituisce l'output, che può essere utilizzato dai sistemi AI per ulteriori elaborazioni o decisioni.
- Repository Pubblico: MCP Terminal è disponibile come repository pubblico, consentendo agli sviluppatori di contribuire, forkare e migliorare il progetto.
Come Utilizzare MCP Terminal
-
Installazione: Clona il repository di MCP Terminal da GitHub sul tuo computer locale.
git clone https://github.com/sichang824/mcp-terminal.git
-
Configurazione: Segui le istruzioni nel repository per impostare l'ambiente e le dipendenze necessarie per eseguire MCP Terminal.
-
Integrazione: Integra MCP Terminal con la tua applicazione AI utilizzando la sua API per inviare comandi e ricevere output.
-
Esecuzione di Comandi: Usa i metodi forniti per eseguire comandi del terminale tramite il tuo modello AI e gestire le risposte di conseguenza.
-
Contribuire: Se hai miglioramenti o funzionalità da aggiungere, considera di forkare il repository e inviare una pull request.
Domande Frequenti
D1: Quali linguaggi di programmazione supporta MCP Terminal?
R1: MCP Terminal è progettato per essere indipendente dal linguaggio, consentendo l'integrazione con qualsiasi linguaggio di programmazione che può effettuare richieste HTTP.
D2: Posso utilizzare MCP Terminal per scopi commerciali?
R2: Sì, MCP Terminal è concesso in licenza sotto la licenza MIT, che consente l'uso commerciale.
D3: Come posso contribuire al progetto MCP Terminal?
R3: Puoi contribuire forkando il repository, apportando le tue modifiche e inviando una pull request. Assicurati di seguire le linee guida per i contributi indicate nel repository.
D4: È disponibile documentazione per MCP Terminal?
R4: Sì, è disponibile una documentazione dettagliata nel repository, comprese le istruzioni di configurazione, l'uso dell'API e esempi.
D5: Quali sono i requisiti di sistema per eseguire MCP Terminal?
R5: MCP Terminal può essere eseguito su qualsiasi sistema che supporti le dipendenze necessarie, richiedendo tipicamente un sistema operativo moderno e un ambiente di runtime compatibile.
Dettaglio
MCP Terminal
MCP Terminal 是一个基于 MCP(Model Context Protocol)的终端控制服务器,专为与大型语言模型(LLM)和 AI 助手集成而设计。它提供了一个标准化的接口,使 AI 可以执行终端命令并获取输出结果。
<a href="https://glama.ai/mcp/servers/@sichang824/mcp-terminal"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@sichang824/mcp-terminal/badge" alt="Terminal MCP server" /> </a>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, 可选):是否等待并返回命令输出,默认为 truetimeout
(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文件。
Configurazione Server
{
"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"
]
}
}
}
}