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

Add to Claude Desktop

Option 1: Using Claude CLI (Recommended)

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

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

Verify Installation

🎯 Usage

MCP Server (Recommended)

Run directly via stdio

Install in Claude Desktop

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

2. Restart Claude Desktop

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

Using with MCP Inspector

GUI Applications

Original Version (threading-based)

UV Version (libuv-based)

🏗️ Architecture

MCP Server Architecture

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

Type Checking

Linting

📝 MCP Protocol Details

Message Format

All messages follow JSON-RPC 2.0 specification:

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