Provides capability to interact with Docker containers through terminal commands like 'docker exec -it' for debugging and management.
Supports debugging of Flask applications with breakpoint setting and request tracing capabilities.
Allows interaction with Git repositories, enabling status checks and execution of Git commands through the terminal.
Enables interaction with Kubernetes clusters through kubectl commands, allowing for pod management and debugging.
Facilitates connection to MySQL databases, authentication handling, and execution of SQL queries through the MySQL client.
Provides interactive debugging of Python scripts through PDB and execution of Python commands in a REPL environment.
Supports connection to Redis instances via Redis CLI, enabling monitoring and management of Redis databases.
Enables attachment to tmux sessions through terminal commands for persistent terminal session management.
Terminal Control MCP Server
A modern MCP server that enables AI agents to control terminal sessions through persistent tmux-based sessions. Features real-time web interface for direct user access, comprehensive security controls, and support for interactive terminal programs including debuggers, SSH connections, and database clients.
✨ Features
🖥️ Tmux-Based Terminal Control
Reliable Backend: Built on tmux and libtmux for stable terminal multiplexing
Session Persistence: Long-running sessions with automatic cleanup and monitoring
Raw Stream Capture: Direct terminal output via tmux pipe-pane
Agent-Controlled: AI agents manage timing and interaction flow without automatic timeouts
Flexible Content Modes: Get screen, history, since-input, or tail output for optimal workflow control
Dual Access: Both agent (MCP tools) and user (web browser) can interact simultaneously
🌐 Optional Web Interface
Real-time Terminal: Live xterm.js terminal emulator with WebSocket updates
Session URLs: Direct browser access to any terminal session
Zero Setup: Automatic web server startup with configurable networking
Manual Control: Send commands directly without interrupting agent workflows
Session Management: View all active sessions and their status
🛡️ Comprehensive Security
Command Filtering: Block dangerous operations (
rm -rf /
,sudo
, disk formatting, etc.)Path Protection: Restrict access to user directories only
Rate Limiting: 60 calls/minute with session limits (max 50 concurrent)
History Isolation: Prevent terminal sessions from polluting system history
Audit Logging: Complete security event tracking
Input Validation: Multi-layer validation for all inputs
Configurable Levels: Off, low, medium, high protection levels
🚀 Quick Start
System Requirements
This package requires tmux
for terminal multiplexing:
Python Requirements: Python 3.9 or later
Installation
From PyPI (Recommended)
From Source
Configuration
The server supports configuration through TOML files and environment variables:
Claude Code (Anthropic)
The MCP server will be automatically launched by Claude Code when needed.
Other MCP Clients
For other MCP clients, add to your configuration:
🔧 Configuration
The server uses TOML configuration files with optional environment variable overrides. Environment variables can override any TOML setting for deployment flexibility.
Configuration File Locations
The server looks for configuration files in this order:
./terminal-control.toml
(current working directory)~/.config/terminal-control.toml
(user configuration directory)/etc/terminal-control.toml
(system-wide configuration)Built-in defaults (if no config file found)
Configuration Sections
[web] - Web Interface Settings
Web Interface Modes:
Enabled: Real-time web interface with xterm.js terminal emulator
Disabled: Automatically opens system terminal windows attached to tmux sessions
Auto Port Selection: When auto_port=true
, ports are automatically selected in the 9000-9999 range using hash(working_dir + process_id) % 1000 + 9000
to avoid conflicts between multiple instances.
[security] - Security Settings
Security Levels:
off
: No validation (⚠️ USE WITH EXTREME CAUTION)low
: Basic input validation onlymedium
: Standard protection (blocks common dangerous commands)high
: Full protection (comprehensive validation and filtering)
[session] - Session Management
History Isolation Features:
Automatic Isolation: Each session gets isolated history files in temporary directories
Multi-Shell Support: Supports bash, zsh, fish, csh, tcsh, Python REPL, Node.js, PostgreSQL, MySQL
Session-Specific Files: History files are prefixed with session IDs for complete isolation
Automatic Cleanup: All history files are automatically deleted when sessions terminate
Configurable: Can be disabled via
isolate_history = false
if system history is preferred
Supported Applications:
Bash:
HISTFILE
,HISTCONTROL
,HISTSIZE
,HISTFILESIZE
Zsh:
HISTFILE
,ZDOTDIR
,SAVEHIST
,HISTSIZE
Fish:
XDG_CONFIG_HOME
,XDG_DATA_HOME
Python:
PYTHONSTARTUP
with readline configurationNode.js:
NODE_REPL_HISTORY
PostgreSQL:
PSQL_HISTORY
MySQL:
MYSQL_HISTFILE
[terminal] - Terminal Settings
Terminal Emulator Support: The system automatically detects available terminal emulators in order of preference:
GNOME/GTK: gnome-terminal
KDE: konsole
XFCE: xfce4-terminal
Elementary OS: io.elementary.terminal
Generic: x-terminal-emulator, xterm
macOS: Terminal (via
open -a Terminal
)Modern terminals: alacritty, kitty, terminator
Custom Terminal Emulator Configuration:
[logging] - Logging Configuration
Complete Configuration Example
Create terminal-control.toml
in your project root:
🛠️ MCP Tools (6 Tools)
The server provides 6 MCP tools for complete terminal session lifecycle management:
Session Management
list_terminal_sessions
List all active terminal sessions with status information.
Returns:
Session IDs, commands, and states
Creation timestamps and last activity
Total session count (max 50)
Web interface URLs (if enabled)
exit_terminal
Terminate and cleanup a terminal session.
Parameters:
session_id
: Session ID to destroy
Features:
Bidirectional cleanup: Sessions destroyed when agents call
exit_terminal
OR when users typeexit
Automatic monitoring: Dead sessions detected and cleaned up every 5 seconds
Terminal window management: Closes associated terminal windows when web interface is disabled
Content Retrieval
get_screen_content
Get terminal content with precise control over output format.
Parameters:
session_id
: Session to get content fromcontent_mode
: Content retrieval mode"screen"
(default): Current visible screen only"since_input"
: Output since last input command"history"
: Full terminal history"tail"
: Last N lines (requiresline_count
)
line_count
: Number of lines for tail mode
Returns:
Terminal content based on mode
Process running status
ISO timestamp for agent timing decisions
Input Control
send_input
Send input to terminal sessions.
Parameters:
session_id
: Target sessioninput_text
: Text to send (supports escape sequences)
Important: Newlines are NOT automatically added. For command execution, explicitly include \n
(e.g., "ls\n"
, "python\n"
).
Features:
Raw input support with escape sequences
No automatic timeouts (agent-controlled timing)
Parallel user input possible via web interface
await_output
🆕
Wait for specific regex patterns to appear in terminal output.
Parameters:
session_id
: Session to monitorpattern
: Regular expression pattern to matchtimeout
: Maximum wait time in seconds (default: 10.0)
Returns:
match_text
: The matched text if pattern found,null
if timeoutscreen_content
: Current screen content when match occurred or timeout reachedelapsed_time
: Time elapsed before match or timeoutsuccess
: Whether operation completed without errors
Features:
Regex pattern matching: Full regular expression support for flexible output detection
Configurable timeout: Control maximum wait time per pattern
Non-blocking: Polls every 100ms without blocking other operations
Precise timing: Returns exact elapsed time for performance optimization
Use Cases:
Wait for build completion:
await_output(session_id, r"Build successful|BUILD SUCCESS", 300.0)
Monitor for errors:
await_output(session_id, r"ERROR|FAILED|Exception", 30.0)
Detect prompt return:
await_output(session_id, r"\$\s*$|>\s*$", 5.0)
Wait for program startup:
await_output(session_id, r"Server running on|Listening on", 60.0)
Session Creation
open_terminal
Create new terminal sessions.
Parameters:
shell
: Shell to use (bash, zsh, fish, sh, etc.)working_directory
: Starting directory (optional)environment
: Environment variables (optional)
Returns:
Unique session ID
Initial screen content
Web interface URL (if enabled)
Process startup status
Features:
Universal shell support
Environment and directory control
Immediate screen content availability
📚 Usage Examples
Basic Commands
Interactive Programs
Debugging Workflow
Using the included examples/example_debug.py
:
Pro tip: If you set web_enabled=true
in your configuration, you can also access the debugging session directly in your browser for real-time interaction.
Web Interface Usage
When web interface is enabled:
Agent creates session:
"Starting debugger session..."
Agent provides URL:
"You can also access it at http://localhost:9123/session/abc123"
User opens URL in browser for direct interaction
Both agent and user can send commands simultaneously
🌐 Web Interface
Real-Time Terminal Access
Live output: See exactly what agents see in real-time
Manual input: Send commands directly without agent awareness
WebSocket updates: Automatic screen refreshes
Session overview: View all active sessions at once
Session URLs
Individual sessions:
http://localhost:8080/session/{session_id}
Session overview:
http://localhost:8080/
Direct browser access: No additional software required
Transparent to agents: Manual interaction doesn't interfere with agent control
🔒 Security
Defense-in-Depth Approach
Command filtering: Blocks dangerous operations (
rm -rf /
,sudo
,dd
, etc.)Path restrictions: Commands run in specified directories only
Input validation: Multi-layer validation for all inputs
Environment protection: Protects critical variables (
PATH
,LD_PRELOAD
, etc.)Rate limiting: Prevents abuse with configurable limits
Audit logging: Complete security event tracking
Agent-Controlled Philosophy
Maximum flexibility: Security balanced with functionality
User responsibility: Security managed by user and agent choices
Transparent operation: All commands create persistent sessions
No hidden automation: Agents control all timing and interaction
📁 Project Structure
🧪 Development
Testing
Code Quality
Development Installation
🚀 Development Status
✅ Tmux Integration: Complete libtmux-based terminal control
✅ Web Interface: Real-time xterm.js with WebSocket synchronization
✅ Agent Control: 6 MCP tools for complete session management
✅ Security Layer: Multi-layer validation and audit logging
✅ TOML Configuration: Structured configuration with environment overrides
✅ Type Safety: Full Pydantic models and mypy coverage
✅ Test Coverage: Comprehensive test suite with multiple categories
✅ Production Ready: Reliable session management with proper cleanup
📄 License
MIT License - see LICENSE file for details.
🤝 Contributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature
)Make your changes and add tests
Ensure all tests pass:
ruff check src/ tests/ && mypy src/ --ignore-missing-imports && pytest tests/Commit your changes (
git commit -m 'Add amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)Open a Pull Request
🙏 Acknowledgments
Built on the Model Context Protocol (MCP) by Anthropic
Uses libtmux for reliable terminal multiplexing
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.
A comprehensive Model Context Protocol server that enables Claude Code to perform expect/pexpect-style automation for interactive programs, supporting complex interactions with terminal programs, SSH sessions, databases, and debugging workflows.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server built with mcp-framework that allows users to create and manage custom tools for processing data, integrating with the Claude Desktop via CLI.Last updated -145
- AsecurityAlicenseAqualityAn implementation of Claude Code as a Model Context Protocol server that enables using Claude's software engineering capabilities (code generation, editing, reviewing, and file operations) through the standardized MCP interface.Last updated -8174MIT License
- AsecurityFlicenseAqualityA Model Context Protocol server that allows integration with Claude Desktop by creating and managing custom tools that can be executed through the MCP framework.Last updated -22
- -securityFlicense-qualityA server implementation for the Model Context Protocol (MCP) that allows Claude AI to execute commands through a command-line interface, enabling direct system interactions from within Claude.Last updated -