使用说明

项目简介

tmux-mcp 服务器是一个基于 Model Context Protocol (MCP) 的后端应用，旨在使 LLM 客户端（如 Claude Desktop）能够与 tmux 会话进行交互。通过此服务器，AI 助手可以读取、控制和观察您的终端会话内容，从而实现更智能的辅助功能。

主要功能点

• 会话管理: 列出和搜索 tmux 会话。
• 窗口和窗格浏览: 查看和导航 tmux 窗口和窗格。
• 内容捕获: 从任何窗格捕获并公开终端内容。
• 命令执行: 在 tmux 窗格中执行命令并检索结果 (请谨慎使用)。
• 会话和窗口创建: 创建新的 tmux 会话和窗口。

安装步骤

1. 安装 Node.js: 确保您的系统已安装 Node.js 运行时环境。您可以从 nodejs.org 下载并安装。
2. 安装 tmux: 确保您的系统已安装 tmux 终端复用器。安装方法取决于您的操作系统。例如，在 Debian/Ubuntu 上可以使用 'sudo apt-get install tmux'，在 macOS 上可以使用 'brew install tmux'。
3. 安装 tmux-mcp: 通过 npm 全局安装 'tmux-mcp' 包。打开终端并执行命令：

   npm install -g tmux-mcp
   

服务器配置

要将 tmux-mcp 服务器添加到 MCP 客户端（例如 Claude Desktop），您需要配置服务器启动命令。在 Claude Desktop 的配置文件中，'mcpServers' 部分添加以下 JSON 配置：

"mcpServers": {
  "tmux": {
    "command": "npx",  // 使用 npx 命令来运行本地安装的 tmux-mcp
    "args": ["tmux-mcp"] // 运行 tmux-mcp 包
  }
}

可选配置：指定 Shell 类型

如果您的默认 shell 不是 bash，您可以通过 '--shell-type' 参数指定 shell 类型。例如，如果您使用 fish shell，配置如下：

"mcpServers": {
  "tmux": {
    "command": "npx",
    "args": ["tmux-mcp", "--shell-type=fish"] // 指定 shell 类型为 fish
  }
}

服务器目前支持 'bash', 'zsh', 'fish' 三种 shell 类型，默认为 'bash'。

基本使用方法

1. 启动 Claude Desktop 或其他 MCP 客户端。

2. 客户端将根据配置自动连接到 tmux-mcp 服务器。

3. 在客户端中，您可以使用以下资源和工具与 tmux 进行交互：

   资源 (Resources):

   • 'tmux://sessions': 列出所有 tmux 会话。
   • 'tmux://pane/{paneId}': 查看指定 tmux 窗格的内容 (需要替换 '{paneId}' 为实际的窗格 ID)。
   • 'tmux://command/{commandId}/result': 获取已执行命令的结果 (需要替换 '{commandId}' 为实际的命令 ID)。

   工具 (Tools):

   • 'list-sessions': 列出所有活动 tmux 会话。
   • 'find-session': 按名称查找 tmux 会话，需要提供 'name' 参数。
   • 'list-windows': 列出 tmux 会话中的窗口，需要提供 'sessionId' 参数。
   • 'list-panes': 列出 tmux 窗口中的窗格，需要提供 'windowId' 参数。
   • 'capture-pane': 捕获 tmux 窗格的内容，需要提供 'paneId' 参数，可选 'lines' 参数指定行数。
   • 'create-session': 创建新的 tmux 会话，需要提供 'name' 参数。
   • 'create-window': 在 tmux 会话中创建新窗口，需要提供 'sessionId' 和 'name' 参数。
   • 'execute-command': 在 tmux 窗格中执行命令，需要提供 'paneId' 和 'command' 参数。返回 commandId 用于后续获取结果。
   • 'get-command-result': 获取已执行命令的结果，需要提供 'commandId' 参数。