Skip to main content
Glama

Tmux MCP Server

by rinadelph
GitHub
Python
MIT License
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

# 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

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
  1. Restart Claude Desktop
  2. 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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

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.

  1. 🚀 Features
    1. MCP Server (tmux_mcp_server.py)
    2. GUI Applications
  2. 📋 Requirements
    1. 🔧 Installation
      1. Prerequisites
      2. Add to Claude Desktop
      3. Verify Installation
    2. 🎯 Usage
      1. MCP Server (Recommended)
      2. GUI Applications
    3. 🏗️ Architecture
      1. MCP Server Architecture
      2. UV Implementation
    4. 🔄 Auto-Cycle Sequence
      1. 🛠️ Development
        1. Running Tests
        2. Type Checking
        3. Linting
      2. 📝 MCP Protocol Details
        1. Message Format
        2. Resources
        3. Error Handling
      3. 🤝 Contributing
        1. 📄 License
          1. 🔗 Related Projects

            Related MCP Servers

            • ticktick-mcp-server

              jacepark12
              -
              security
              F
              license
              -
              quality
              A MCP server for TickTick that enables interacting with your TickTick task management system directly through Claude and other MCP clients.
              Last updated -
              121
              • Apple

            • ClaudeKeep

              sdairs
              A
              security
              A
              license
              A
              quality
              An 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 -
              2
              11
              MIT License
              • Apple

            • Claude Desktop Commander MCP

              wonderwhy-er
              A
              security
              A
              license
              A
              quality
              Allows 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 -
              21
              23,153
              4,274
              MIT License
              • Apple

            • Tmux MCP Server

              nickgnd
              A
              security
              A
              license
              A
              quality
              Enables Claude Desktop to interact with and view tmux session content, allowing AI assistants to read from, control, and observe terminal sessions.
              Last updated -
              9
              289
              91
              MIT License
              • Linux
              • Apple

            View all related MCP servers

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/rinadelph/tmux-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server