使用说明

🖥️ MCP终端服务器

通过模型上下文协议（MCP）进行交互式终端会话

MCP终端服务器为Windows、Linux和macOS提供跨平台PTY（伪终端）支持，通过REST API和MCP协议公开终端会话。非常适合AI助手、远程终端访问和终端自动化。

✨ 特性

🌍 跨平台：适用于Windows（cmd.exe/PowerShell）、Linux和macOS
🔄 真正的PTY：支持交互式命令（vim、nano、htop等）
👁️ 可视化快照：捕捉人类在终端屏幕上看到的内容
🔤 UTF-8支持：正确处理特殊字符和表情符号
🚀 MCP协议：通过fastapi-MCP自动将所有端点作为MCP工具公开
📡 REST API：带有FastAPI的完整HTTP/REST API
🎯 多个会话：同时管理多个终端会话

📦 安装

来自PyPI

pip install mcp-terminal

来源

git clone https://github.com/alejoair/mcp-terminal
cd mcp-terminal
pip install -e .

🚀 快速开始

启动服务器

# Start on default port (8777)
mcp-terminal

# Start on custom port
mcp-terminal --port 9000

# Development mode with auto-reload
mcp-terminal --reload

# Custom host and port
mcp-terminal --host 0.0.0.0 --port 8888

访问服务器

运行后，您可以访问：

API 文档: http://localhost:8777/docs
MCP端点: http://localhost:8777/mcp
健康检查: http://localhost:8777/health

📖 用法

REST API

创建终端

curl -X POST http://localhost:8777/terminals \
  -H "Content-Type: application/json" \
  -d '{"rows": 24, "cols": 80}'

答复：

{
  "success": true,
  "terminal_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Terminal created successfully"
}

发送命令

curl -X POST http://localhost:8777/terminals/{terminal_id}/input \
  -H "Content-Type: application/json" \
  -d '{"data": "echo Hello World\n"}'

获取可视化快照

curl http://localhost:8777/terminals/{terminal_id}/snapshot

答复：

{
  "terminal_id": "550e8400-e29b-41d4-a716-446655440000",
  "display": "C:\\Users\\...\nHello World\nC:\\Users\\...> ",
  "lines": ["C:\\Users\\...", "Hello World", "C:\\Users\\...> "],
  "cursor": {"row": 2, "col": 15},
  "size": {"rows": 24, "cols": 80},
  "is_alive": true,
  "created_at": "2024-01-01T00:00:00"
}

列出终端

curl http://localhost:8777/terminals

调整终端大小

curl -X PUT http://localhost:8777/terminals/{terminal_id}/resize \
  -H "Content-Type: application/json" \
  -d '{"rows": 30, "cols": 100}'

关闭终端

curl -X DELETE http://localhost:8777/terminals/{terminal_id}

MCP工具

当与MCP客户端（如Claude Desktop）一起使用时，以下工具会自动可用：

create_terminal_terminals__post -创建新终端
list_terminals_terminals__get -列出活动终端
get_terminal_snapshot_terminals__terminal_id__snapshot_get -获取可视快照
send_terminal_input_terminals__terminal_id__input_post -发送命令
resize_terminal_terminals__terminal_id__resize_put -调整终端大小
close_terminal_terminals__terminal_id__delete -关闭终端

Python API

from mcp_terminal import TerminalManager

# Create manager
manager = TerminalManager()

# Create terminal
terminal_id = await manager.create(rows=24, cols=80)

# Send input
await manager.send_input(terminal_id, "echo Hello\n")

# Get snapshot
snapshot = await manager.get_snapshot(terminal_id)
print(snapshot["display"])

# Close terminal
await manager.close(terminal_id)

🏗️ 建筑

src/mcp_terminal/
├── __init__.py          # Package initialization
├── __main__.py          # CLI entry point
├── server.py            # FastAPI application with MCP integration
├── core/
│   └── terminal/
│       ├── session.py   # TerminalSession - PTY management
│       ├── buffer.py    # TerminalBuffer - Visual screen capture
│       └── manager.py   # TerminalManager - Multi-session coordinator
└── models/
    └── terminal.py      # Pydantic models for API

🔧 配置

命令行选项

--host HOST          Host to bind to (default: 127.0.0.1)
--port PORT          Port to bind to (default: 8777)
--reload             Enable auto-reload for development
--log-level LEVEL    Set log level (debug, info, warning, error, critical)
--version            Show version and exit

环境变量

您还可以通过环境变量进行配置：

export MCP_TERMINAL_HOST=0.0.0.0
export MCP_TERMINAL_PORT=9000
export MCP_TERMINAL_LOG_LEVEL=debug

🧪 测试

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=mcp_terminal

🤝 贡献

欢迎投稿！请随时提交拉取请求。

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

内置于快速API
用途完成用于跨平台PTY支持
用途 pyte 用于终端仿真
MCP集成通过 fastapi mcp

📚 资源

🐛 错误报告

如果你发现一个bug，请在 GitHub.

💬 支持

如有疑问和支持，请使用 GitHub讨论.

由以下材料制成❤️ MCP终端团队