Integrates with Mullvad VPN as part of automated cycle operations, allowing programmatic reconnection commands to be executed within tmux sessions.
Provides comprehensive tmux session management capabilities including listing sessions, sending commands and messages to specific sessions, setting up automated message timers, controlling auto-cycle sequences, and sending control signals like Ctrl+C to running sessions.
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
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
Copy the configuration to Claude Desktop's config directory:
Restart Claude Desktop
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 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
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 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
🔗 Related Projects
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables comprehensive tmux session management through MCP, allowing users to list sessions, send commands, set up automated messaging timers, and control tmux processes directly from Claude Desktop. Provides both real-time session monitoring and automated workflow features like exit/continue cycles.
Related MCP Servers
- -securityFlicense-qualityA MCP server for TickTick that enables interacting with your TickTick task management system directly through Claude and other MCP clients.Last updated -146
- AsecurityAlicenseAqualityAn MCP server that enables saving and sharing Claude Desktop conversations, allowing users to store chats privately or make them public through a web interface.Last updated -10MIT License
- AsecurityAlicenseAqualityAllows Claude desktop app to execute terminal commands and edit files on your computer through MCP, with features including command execution, process management, and diff-based file editing.Last updated -2122,9694,607MIT License
- AsecurityAlicenseAqualityEnables Claude Desktop to interact with and view tmux session content, allowing AI assistants to read from, control, and observe terminal sessions.Last updated -9113134MIT License