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 sessionssend_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 sendingstop_message_timer: Stop active timersstart_auto_cycle: Start automated exit/continue cyclesstop_auto_cycle: Stop active cyclessend_ctrl_c: Send Ctrl+C signals to sessions
- Resources:
tmux://sessions: Real-time session informationtmux://timers: Active timer statustmux://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
- 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
-
Restart Claude Desktop
-
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 looppyuv.Process: Non-blocking process spawningpyuv.Timer: Precise timer operationspyuv.Pipe: Process I/O handlingpyuv.StdIO: stdio configuration
🔄 Auto-Cycle Sequence
The auto-cycle feature performs:
- Send Ctrl+C 5 times (200ms apart)
- Wait 1 second
- Execute
mullvad reconnect - Wait 3 seconds
- Execute
claudex -c - 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 sessionstmux://timers- Active timer informationtmux://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
- Fork the repository
- Create a feature branch
- Implement your changes with tests
- Ensure type checking and linting pass
- Submit a pull request
📄 License
MIT License - See LICENSE file for details