# 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
```bash
# Install Python dependencies
pip install -r requirements.txt

# Or using uv (recommended)
uv sync
```

### Add to Claude Desktop

#### Option 1: Using Claude CLI (Recommended)
```bash
# 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`

```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
```bash
# 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
```bash
python tmux_mcp_server.py
```

#### Install in Claude Desktop
1. Copy the configuration to Claude Desktop's config directory:
```bash
# 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
```bash
# Test the server
npx @modelcontextprotocol/inspector python tmux_mcp_server.py
```

### GUI Applications

#### Original Version (threading-based)
```bash
python tmux_messenger.py
```

#### UV Version (libuv-based)
```bash
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
```bash
pytest tests/
```

### Type Checking
```bash
pyright tmux_mcp_server.py
```

### Linting
```bash
ruff check .
ruff format .
```

## 📝 MCP Protocol Details

### Message Format
All messages follow JSON-RPC 2.0 specification:
```json
{
  "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](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [libuv](https://libuv.org)