AI导哈

tmux终端交互服务器

MCP Tmux Server是一个实时tmux终端交互服务，支持AI助手执行命令和读取终端输出。

  • by Zdendys79
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Zdendys79/mcp-tmux-server

使用说明

MCP Tmux服务器

用于实时tmux终端交互的MCP（模型上下文协议）服务器。使Claude Code等AI助手能够执行命令和读取终端输出。

先决条件

重要： 克劳德代码（或任何MCP客户端） 必须在tmux会话内运行 使用后台回调功能。回调通知通过以下方式传递 tmux send-keys 到客户的会话。

# Start Claude Code in a tmux session
tmux new -s claude
claude   # start Claude Code inside the tmux session

没有tmux， run_wait 仍然适用于短命令（同步模式），但是 run_background的回叫无法送达。如果回调传递失败，则会在运行该命令的源tmux会话中打印错误消息。

特性

  • 会话前缀解析 -使用短前缀而不是全名（例如。 sudo → sudo-0)；不明确的前缀返回候选错误
  • 同步执行 -阻塞直到命令完成（默认最多10秒）
  • 带回调的后台监控 -异步监视长时间运行的命令；完成后发送通知
  • 安静的回拨交付 -在发送之前等待10秒不活动，从不中断用户键入
  • 实时终端读取 -没有什么，总是新鲜的内容
  • 键盘快捷键 -发送Ctrl+C、Ctrl+D、箭头、功能键
  • 文本输入 -在交互式程序（编辑器、提示）中键入文本
  • 会话管理 -列出、检查和创建tmux会话
  • 安全 -默认情况下为只读，会话白名单支持

安装

cd ~/mcp-servers
git clone git@github.com:Zdendys79/mcp-tmux-server.git tmux
cd tmux
npm install
npm run build

添加到 ~/.claude.json:

{
  "mcpServers": {
    "tmux": {
      "command": "node",
      "args": ["/home/zdendys/mcp-servers/tmux/dist/index.js"]
    }
  }
}

在中启用写入模式 ~/.config/mcp-tmux/config.json:

{
  "version": "auto",
  "write_enabled": true,
  "allowed_sessions": [],
  "buffer_size": 1000,
  "auth_token": null
}

快速开始

// Short command - blocks and returns the result directly. Hard-capped at 120s no matter what
// `timeout` you pass, so a units mistake (seconds vs ms) can never turn this into an hours-long
// block -- if a command might take longer, use run_background instead.
const result = await run_wait({session: "work", command: "ls -la"});

// Long-running / never-returning command - does NOT block. Sends the command, waits a short
// grace period to catch immediate failures, then returns control immediately either way.
const result = await run_background({
  session: "base7",
  command: "sudo apt upgrade -y",
  callback_session: "claude-9",   // REQUIRED: where to deliver the "done" notification
  max_monitor: 600                // raise for multi-hour jobs, e.g. 14400 = 4h
});
// Returns immediately with status: "background"
// Notification (with output) sent to claude-9 session whenever the command actually finishes

MCP工具

工具 说明
run_wait 运行SHORT命令并阻塞结果（硬上限为120秒）
run_background 无阻塞地运行LONG-RUNNING命令；通知 callback_session 完成后
read_tmux_pane 读取当前终端内容（始终保持新鲜）
type_text 在编辑器/提示中键入文本（不用于命令）
send_key 发送键盘快捷键（Ctrl+C、箭头等）
get_tmux_sessions 列出所有活动的tmux会话及其状态
get_pane_info 获取窗格尺寸，运行命令
list_background_tasks 列出活动的后台任务监视器
get_server_version 获取服务器版本
create_session 使用自动递增命名创建新的tmux会话

文档

  • 工具参考 -所有工具的完整参数和返回值文档
  • 建筑 -数据流、提示检测、后台回调、安全、配置
  • 更新日志 -版本历史和发行说明

故障排除

MCP服务器未启动：

tmux -V          # Check tmux is installed
node dist/index.js  # Test server manually

未执行的命令：

  • 检查 write_enabled: true 在配置中
  • 验证会话是否存在： tmux list-sessions
  • 检查 allowed_sessions 白名单（如果已设置）

回拨未送达：

  • 确保Claude代码在tmux内部运行： tmux new -s claude
  • 检查 list_background_tasks 用于活动监视器
  • 如果传递失败，源终端将显示错误消息

发展

npm install      # Install dependencies
npm run build    # Build TypeScript
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js  # Test

许可证

MIT许可证

作者

由Zdendys&Nyara创建，用于Claude代码集成

链接

  • github： https://github.com/Zdendys79/mcp-tmux-server
  • MCP协议： https://modelcontextprotocol.io/
  • MCP-SDK： https://github.com/modelcontextprotocol/typescript-sdk

相关 MCP