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 execute 该工具仍然适用于短命令（同步模式），但无法传递后台监控回调。如果回调传递失败，则会在运行该命令的源tmux会话中打印错误消息。

特性

• 同步执行 -阻塞直到命令完成（默认最多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 - synchronous
const result = await execute({session: "work", command: "ls -la"});

// Long command - background monitoring with callback
const result = await execute({
  session: "base7",
  command: "sudo apt upgrade -y",
  timeout: 10,
  callback_session: "claude-9",
  max_monitor: 600
});
// Returns immediately with status: "background"
// Notification sent to claude-9 session when done

MCP工具

文档

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

故障排除

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