rinadelph/tmux-mcp

Tmux MCP Server

A comprehensive tmux control system implementing the Model Context Protocol (MCP) for seamless integration with Claude Desktop and other MCP-compatible clients. This project provides multiple interfaces for tmux session management, including a GUI application, UV-based async implementation, and a full MCP stdio server.

🚀 Features

MCP Server (tmux_mcp_server.py)

• Full MCP Protocol Implementation: JSON-RPC 2.0 over stdio
• Tools:
  • list_tmux_sessions: List all active tmux sessions
  • send_message_to_session: Send messages (types, waits 1s, then Enter)
  • launch_agent: Launch AI agents (gemini, claude, codex, swarm)
  • start_message_timer: Set up repeated message sending
  • stop_message_timer: Stop active timers
  • start_auto_cycle: Start automated exit/continue cycles
  • stop_auto_cycle: Stop active cycles
  • send_ctrl_c: Send Ctrl+C signals to sessions
• Resources:
  • tmux://sessions: Real-time session information
  • tmux://timers: Active timer status
  • tmux://cycles: Auto-cycle status
• Prompts: Pre-defined templates for common operations

GUI Applications

• tmux_messenger.py: Threading-based GUI with Tkinter
• tmux_messenger_uv.py: High-performance UV (libuv) event loop implementation

📋 Requirements

• Python 3.8+
• tmux installed on system
• MCP SDK (mcp>=0.9.0)
• pyuv library (for UV version)
• tkinter (usually comes with Python)

🔧 Installation

Prerequisites

# Install Python dependencies
pip install -r requirements.txt

# Or using uv (recommended)
uv sync

Add to Claude Desktop

Option 1: Using Claude CLI (Recommended)

# Clone the repository
git clone https://github.com/rinadelph/tmux-mcp.git
cd tmux-mcp

# Add to Claude (user-level, available in all sessions)
claude mcp add --scope user --transport stdio tmux-control python "$(pwd)/tmux_mcp_server.py"

# Or add locally (current project only)
claude mcp add --transport stdio tmux-control python "$(pwd)/tmux_mcp_server.py"

Option 2: Manual Configuration

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tmux-control": {
      "command": "python",
      "args": [
        "/absolute/path/to/tmux-mcp/tmux_mcp_server.py"
      ],
      "env": {}
    }
  }
}

Replace /absolute/path/to/tmux-mcp/ with the actual path where you cloned the repository.

Verify Installation

# Check if the server is connected
claude mcp list

# You should see:
# tmux-control: python /path/to/tmux_mcp_server.py - ✓ Connected

🎯 Usage

MCP Server (Recommended)

Run directly via stdio

python tmux_mcp_server.py

Install in Claude Desktop

1. Copy the configuration to Claude Desktop's config directory:

# macOS
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
cp claude_desktop_config.json ~/.config/Claude/claude_desktop_config.json

# Windows
copy claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json

2. Restart Claude Desktop

3. The tmux server will be available in Claude's MCP tools

Using with MCP Inspector

# Test the server
npx @modelcontextprotocol/inspector python tmux_mcp_server.py

GUI Applications

Original Version (threading-based)

python tmux_messenger.py

UV Version (libuv-based)

python tmux_messenger_uv.py

🏗️ Architecture

MCP Server Architecture

Client (Claude) <-> JSON-RPC 2.0 <-> stdio <-> MCP Server <-> tmux

The MCP server:

• Reads JSON-RPC messages from stdin
• Writes responses to stdout
• Logs to stderr (critical for MCP protocol compliance)
• Manages async tasks for timers and cycles
• Provides real-time resources via URI scheme

UV Implementation

• pyuv.Loop: Main event loop
• pyuv.Process: Non-blocking process spawning
• pyuv.Timer: Precise timer operations
• pyuv.Pipe: Process I/O handling
• pyuv.StdIO: stdio configuration

🔄 Auto-Cycle Sequence

The auto-cycle feature performs:

1. Send Ctrl+C 5 times (200ms apart)
2. Wait 1 second
3. Execute mullvad reconnect
4. Wait 3 seconds
5. Execute claudex -c
6. Repeat every 4 minutes (configurable)

🛠️ Development

Running Tests

pytest tests/

Type Checking

pyright tmux_mcp_server.py

Linting

ruff check .
ruff format .

📝 MCP Protocol Details

Message Format

All messages follow JSON-RPC 2.0 specification:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "send_message_to_session",
    "arguments": {
      "session_name": "main",
      "message": "echo 'Hello from MCP'"
    }
  },
  "id": 1
}

Resources

Resources are accessed via URI scheme:

• tmux://sessions - List of current sessions
• tmux://timers - Active timer information
• tmux://cycles - Auto-cycle status

Error Handling

• All errors are logged to stderr
• Tools return structured error responses
• Async operations are properly cancelled on shutdown

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes with tests
4. Ensure type checking and linting pass
5. Submit a pull request

📄 License

MIT License - See LICENSE file for details

🔗 Related Projects

• Model Context Protocol
• MCP Python SDK
• libuv