Terminally MCP

🖥️ 终端MCP

配备终端控制功能的AI助手 ⚡

 ](https://nodejs.org)  

*让你的AI助手像专业开发人员一样创建、管理和控制终端会话！基于模型上下文协议（MCP）构建，可与Claude、ChatGPT等人工智能工具无缝集成。*

特性 • 快速开始 • 安装 • api参考 • 例子

______________________________________________________________________

🎯 什么是终端MCP？

最终，MCP是一种 模型上下文协议（MCP）服务器 这弥合了人工智能助手和终端操作之间的差距。它提供了一个安全、可控的环境，人工智能可以：

• 🚀 执行shell命令 具有完整的输出捕获功能
• 📂 管理多个终端会话 同时
• 🔍 读取终端历史记录 以及回滚缓冲区
• 🛡️ 隔离的tmux环境 这不会干扰您现有的会话
• ⚡ 实时命令执行 具有超时保护

非常适合人工智能驱动的开发工作流程、自动化、系统管理和交互式编码辅助！

✨ 特性

🎮 终端控制

• 创建和管理多个终端选项卡
• 使用正确的引号/转义处理执行命令
• 捕获命令输出和退出代码
• 读取终端历史记录并回滚

🔒 安全与隔离

• 专用tmux服务器实例
• 不干扰用户的tmux会话
• 长时间运行命令的超时保护
• 清洁会话管理

🤖 AI优化

• MCP协议合规性
• 结构化JSON响应
• 错误处理和恢复
• 基于标记的输出捕获

🛠️ 开发者友好

• 具有完全类型安全的TypeScript
• 全面的测试套件
• 干净、模块化的架构
• 易于扩展和定制

🚀 快速开始

2分钟内起床跑步！

# Clone the repository
git clone https://github.com/yourusername/terminally-mcp.git
cd terminally-mcp

# Install dependencies (we recommend pnpm for speed!)
pnpm install

# Build the TypeScript code
pnpm build

# Start the MCP server
pnpm start

就是这样！服务器现在已准备好接受MCP连接。

📦 安装

先决条件

• Node.js v16或更高版本
• 子速率复用器 安装在您的系统上
• pnpm （推荐）或npm/yarn

安装tmux

🍎 macOS

brew install tmux

🐧 Linux

# Ubuntu/Debian
sudo apt-get install tmux

# Fedora
sudo dnf install tmux

# Arch
sudo pacman -S tmux

AI助手设置

🤖 Claude Desktop (via MCP)

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "terminally-mcp": {
      "command": "node",
      "args": ["/path/to/terminally-mcp/build/index.js"]
    }
  }
}

⚡ Cline/Other MCP Clients

添加到MCP客户端配置中：

{
  "terminally-mcp": {
    "command": "node",
    "args": ["/path/to/terminally-mcp/build/index.js"],
    "type": "stdio"
  }
}

📖 api参考

🔧 可用工具

create_tab

创建新的终端会话。

// Request
{
  "name": "my-session"  // Optional: custom name for the tab
}

// Response
{
  "window_id": "@1"  // Unique identifier for the created tab
}

execute_command

在特定的终端选项卡中运行任何shell命令。

// Request
{
  "window_id": "@1",
  "command": "echo 'Hello, World!' && ls -la",
  "timeout": 5000  // Optional: timeout in ms (default: 10000)
}

// Response
{
  "output": "Hello, World!\ntotal 64\ndrwxr-xr-x  10 user  staff  320 Jan 15 10:00 ."
}

list_tabs

获取所有活动的终端会话。

// Response
{
  "tabs": [
    {
      "window_id": "@0",
      "name": "default",
      "active": true
    },
    {
      "window_id": "@1",
      "name": "my-session",
      "active": false
    }
  ]
}

read_output

读取终端缓冲区，包括历史记录。

// Request
{
  "window_id": "@1",
  "history_limit": 100  // Optional: number of history lines
}

// Response
{
  "content": "$ echo 'Previous command'\nPrevious command\n$ ls\nfile1.txt file2.txt"
}

close_tab

关闭终端会话。

// Request
{
  "window_id": "@1"
}

// Response
{
  "success": true
}

💡 例子

基本命令执行

// Create a new terminal
const tab = await mcp.call('create_tab', { name: 'dev-server' });

// Navigate and start a development server
await mcp.call('execute_command', {
  window_id: tab.window_id,
  command: 'cd /my/project && npm run dev'
});

// Check the output
const output = await mcp.call('read_output', {
  window_id: tab.window_id
});

多选项卡工作流

// Create tabs for different purposes
const webTab = await mcp.call('create_tab', { name: 'web-server' });
const dbTab = await mcp.call('create_tab', { name: 'database' });
const testTab = await mcp.call('create_tab', { name: 'tests' });

// Start services in parallel
await Promise.all([
  mcp.call('execute_command', {
    window_id: webTab.window_id,
    command: 'npm run dev'
  }),
  mcp.call('execute_command', {
    window_id: dbTab.window_id,
    command: 'docker-compose up postgres'
  })
]);

// Run tests
await mcp.call('execute_command', {
  window_id: testTab.window_id,
  command: 'npm test'
});

复杂的指挥链

// Execute multiple commands with proper escaping
await mcp.call('execute_command', {
  window_id: '@1',
  command: `
    echo "Setting up environment..." &&
    export NODE_ENV=development &&
    echo "Installing dependencies..." &&
    npm install &&
    echo "Running migrations..." &&
    npm run migrate &&
    echo "Starting application..." &&
    npm start
  `.trim()
});

🏗️ 建筑

terminally-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── services/
│   │   └── tmuxManager.ts    # tmux interaction layer
│   └── tools/
│       ├── definitions.ts    # Tool schemas
│       └── handlers.ts       # Tool implementations
├── test/                     # Test suite
├── build/                    # Compiled JavaScript
└── package.json

关键设计决策

• 🔐 隔离tmux服务器：每个实例都使用唯一的套接字路径来防止冲突
• 📍 基于标记的输出捕获：使用UUID标记进行可靠的命令输出提取
• ⏱️ 超时保护：可配置的超时可防止挂起长时间运行的命令
• 🎯 类型安全：具有严格类型的完整TypeScript实现

🧪 发展

# Run in development mode (auto-rebuild)
pnpm dev

# Run tests
pnpm test

# Run tests with UI
pnpm test:ui

# Build for production
pnpm build

# Start production server
pnpm start

🤝 贡献

我们热爱贡献！无论是：

• 🐛 错误报告
• 💡 功能请求
• 📖 文档改进
• 🔧 代码贡献

请随时：

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

📄 许可证

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

🙏 致谢

• 建立在 模型上下文协议 规格
• 由...驱动 子速率复用器 -终端多路复用器
• 受更好的AI终端集成需求的启发

🌟 明星历史

如果你觉得这个项目有用，请考虑给它一个⭐ 在GitHub上！

______________________________________________________________________

内置于❤️ 面向人工智能辅助开发社区