Interactive Automation MCP Server

Terminal Control MCP Server

A modern MCP server built with tmux/libtmux that enables AI agents to control terminal programs through persistent sessions. Features real-time web interface for direct user access, comprehensive security controls, and support for any terminal program from simple commands to complex interactive workflows like debugging, SSH, and database sessions.

✨ Features

🚀 Tmux-Based Terminal Control

🖥️ Tmux Backend: Reliable terminal multiplexing with libtmux Python API
🔄 Session Persistence: Maintain long-running terminal sessions with automatic cleanup
📡 Raw Stream Capture: Direct terminal output via tmux pipe-pane for perfect synchronization
🎯 Agent Control: AI agents decide timing and interaction flow without timeouts
🌐 Dual Access: Both agent (MCP) and user (web browser) can interact simultaneously

🌐 Integrated Web Interface

🖥️ Real-time Terminal: Live xterm.js terminal in browser 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 agent awareness
📊 Session Management: View all active sessions and their status

🛡️ Comprehensive Security

🚫 Command Filtering: Block dangerous operations (rm -rf /, sudo, etc.)
📁 Path Protection: Restrict access to user directories only
⏱️ Rate Limiting: 60 calls/minute with session limits (max 50 concurrent)
📝 Audit Logging: Complete security event tracking
🔍 Input Validation: Multi-layer validation for all inputs

🚀 Quick Start

System Requirements

This package requires tmux for terminal multiplexing:

# Ubuntu/Debian
sudo apt update && sudo apt install -y tmux

# macOS
brew install tmux

# CentOS/RHEL/Fedora
sudo yum install tmux  # or sudo dnf install tmux

Installation

# Create virtual environment
uv venv
source .venv/bin/activate

# Install the package
pip install .

# Or install in development mode
pip install -e ".[dev]"

Configuration

Once installed, configure the MCP server in your AI assistant:

🎯 Platform Setup

🤖 Claude Code (Anthropic)

Install the package first (required for console script):
# Install the package to create the console script pip install .
Add the MCP server using Claude Code CLI:
# Recommended: User scope (available across all projects) claude mcp add terminal-control -s user terminal-control-mcp # Alternative: Local scope (default - current project only) claude mcp add terminal-control terminal-control-mcp # Alternative: Project scope (shared via .mcp.json in version control) claude mcp add terminal-control -s project terminal-control-mcp
Verify the server was added:
claude mcp list

Note: The MCP server will be automatically launched by Claude Code when needed - no manual activation required.

Web Interface: When the server starts, it automatically launches a web interface (default port 8080) where users can directly view and interact with terminal sessions through their browser. The interface is automatically configured for local or remote access based on your environment settings.

🔧 Visual Studio Code with GitHub Copilot

Configure in VS Code settings (MCP extension or built-in support):
- Open Settings (Ctrl+, or Cmd+,)
- Search for "MCP" or "Model Context Protocol"
- Add server configuration:
{ "mcp.servers": { "terminal-control": { "command": "/path/to/terminal-control-mcp/.venv/bin/python", "args": ["-m", "terminal_control_mcp.main"], "cwd": "/path/to/terminal-control-mcp" } } }
Alternative configuration using console script:
{ "mcp.servers": { "terminal-control": { "command": "/path/to/terminal-control-mcp/.venv/bin/terminal-control-mcp", "cwd": "/path/to/terminal-control-mcp" } } }
Reload VS Code to apply the configuration

🌐 Web Interface

Each terminal session is accessible through a web interface that provides:

✨ Real-Time Terminal Access

Live terminal output - See exactly what agents see in real-time
Manual input capability - Send commands directly to sessions without going through the agent
WebSocket updates - Automatic screen refreshes as output changes
Session management - View all active sessions and their status

🔗 Session URLs

Individual session pages: http://localhost:8080/session/{session_id}
Session overview: http://localhost:8080/ (lists all active sessions)
Direct browser access - No additional software needed
Transparent to agents - Agents remain unaware of direct user interaction

⚙️ Configuration

Local Development

# Default configuration - web interface only accessible locally
export TERMINAL_CONTROL_WEB_HOST=127.0.0.1   # Default: 0.0.0.0 (changed for security)
export TERMINAL_CONTROL_WEB_PORT=8080        # Default: 8080

Remote/Network Access

# For MCP servers running on remote machines
export TERMINAL_CONTROL_WEB_HOST=0.0.0.0            # Bind to all interfaces
export TERMINAL_CONTROL_WEB_PORT=8080               # Choose available port
export TERMINAL_CONTROL_EXTERNAL_HOST=your-server.com  # External hostname/IP for URLs

Remote Access Example:

MCP server runs on server.example.com
Set TERMINAL_CONTROL_EXTERNAL_HOST=server.example.com
Users access sessions at http://server.example.com:8080/session/{session_id}
Agent logs show the correct external URLs for sharing

🛠️ Complete Tool Set (5 Agent-Controlled Tools)

📋 Session Management (2 tools)

`tercon_list_sessions`

List all active terminal sessions with detailed status information.

Shows comprehensive session information:

Session IDs and commands for identification
Session states (active, waiting, error, terminated)
Creation timestamps and last activity times
Total session count (max 50 concurrent)
Web interface URLs logged for user access

`tercon_destroy_session`

Terminate and cleanup a terminal session safely.

🤖 Agent-Controlled Interaction (2 tools)

`tercon_get_screen_content`

Get current terminal screen content with timestamp.

Key features:

Returns current terminal output visible to user
Includes ISO timestamp for agent timing decisions
Process running status
Agents decide when to wait longer based on timestamps

Agent workflow:

Call tercon_get_screen_content to see current terminal state
Analyze screen content and timestamp
Decide whether to wait longer or take action
Use tercon_send_input when process is ready for input

User access: Same content visible in web interface for direct interaction

`tercon_send_input`

Send text input to a terminal session.

Features:

Send any text input to the running process
Automatic newline appending
No timeouts - agents control timing
Works with any terminal program
Parallel user input possible through web interface

🔗 Session Creation (1 tool)

`tercon_execute_command`

Execute any command and create a terminal session.

Universal command execution:

ANY command: ssh host, python script.py, ls, docker run -it image, make install
ALL commands create persistent sessions (interactive and non-interactive)
Process startup timeout only (default: 30 seconds)
Environment variables and working directory control
NO output returned - agents must use tercon_get_screen_content to see terminal state
Returns session ID for agent-controlled interaction
Web interface URL logged for direct user access

Agent-controlled workflow:

tercon_execute_command - Creates session and starts process
tercon_get_screen_content - Agent sees current terminal state (output or interface) with timestamp
tercon_send_input - Agent sends input if process is waiting for interaction
Repeat steps 2-3 as needed (agent controls timing)
tercon_destroy_session - Clean up when finished (REQUIRED for all sessions)

📚 Usage Examples & Tutorial

Prerequisites

Python 3.10+ installed
Claude Code CLI installed and configured
Basic familiarity with command line tools

Quick Start Commands

# Install and activate
pip install -e ".[dev]"
claude mcp add terminal-control -s user terminal-control-mcp

# Verify installation
claude mcp list

# Test
python tests/conftest.py

Essential Tool Examples

Basic Commands

# Just ask Claude naturally:
"Start a Python session and show me what's on screen"
"List all my active terminal sessions" 
"What's currently showing in the terminal?"
"Type 'print(2+2)' in the Python session"
"Close that debugging session for me"

# Claude will provide web interface URLs for direct access:
# "Session created! You can also access it directly at http://localhost:8080/session/session_abc123"

Interactive Programs

# Natural requests:
"Start a Python REPL and help me calculate 2+2"
"SSH into that server and check disk space" 
"Connect to mysql and show me the tables"
"Debug this script and set some breakpoints"
"Run ls -la and tell me what files are there"
"Check git status and tell me what changed"

Complex Workflows

# Just describe what you want:
"Debug this Python script - set a breakpoint and step through it"
"SSH to the server, enter my password when prompted, then check logs"
"Install this software and handle any prompts that come up"

🌐 Web Interface Usage Examples

Direct Terminal Access

# After creating a session with Claude:
Claude: "I've started a Python debugger session. You can also access it directly at http://localhost:8080/session/session_abc123"
User opens the URL in browser
User sees live terminal output and can type commands directly
Both agent and user can interact with the same session simultaneously

Monitoring Long-Running Processes

# For monitoring builds, deployments, or long-running scripts:
Agent starts process: "Starting your build process..."
User opens web interface to monitor progress in real-time
User can send manual commands if needed (like stopping the process)
Agent continues to monitor and respond as needed

🐛 Complete Debugging Tutorial with `examples/example_debug.py`

This walkthrough shows how to debug a real Python script using natural language with Claude.

Getting Started

> "Debug the file examples/example_debug.py and show me what we're working with"

Claude will start the Python debugger and show you:

> /path/to/examples/example_debug.py(36)main()
-> print("Starting calculations...")
(Pdb) 

Pro tip: Claude will also provide a web interface URL where you can view the same debugger session in your browser and send commands directly if needed.

Exploring the Code

> "Show me the source code around the current line"

Claude types l in the debugger and you see the code context.

Finding the Bug

> "Set a breakpoint where the bug is, then run the program"

Claude sets the breakpoint with b [line_number], continues with c, and the program runs until it hits the buggy loop.

Investigating Variables

> "What variables do we have here? Show me their values"

Claude uses pp locals() to show you all the local variables at that point.

Understanding the Problem

> "Step through this loop and show me what's happening with the index"

Claude steps through with n and checks p i, len(data) to reveal the off-by-one error.

Wrapping Up

> "We found the bug! Clean up this debugging session"

Claude terminates the debugger and cleans up the session.

Advanced Usage Examples

Multi-Step Interactive Sessions

Python Debugging:

"Start a Python debugger session, wait for the (Pdb) prompt, set a breakpoint, then continue execution and examine variables when we hit it."

SSH Session Management:

"Connect to SSH server, wait for password prompt, authenticate, then navigate to log directory and monitor the latest log file."

Database Interaction:

"Start mysql client, wait for connection, authenticate when prompted, then show databases and describe table structure."

Real-World Applications

Development Workflows:

Interactive debugging with GDB, PDB, LLDB
Git operations requiring user input
Docker container interaction
Kubernetes pod debugging

System Administration:

SSH server management
Database administration
Interactive installers and configurators
System monitoring and diagnostics

Testing and QA:

Interactive test runners
Manual testing of CLI tools
Integration testing across systems

Troubleshooting

Common Issues

Session Won't Start:

Verify the command exists and is executable
Check file permissions and paths
Ensure working directory is correct

Process Not Responding:

Use tercon_get_screen_content to see current state
Check timestamps to see if output is recent
Look for blocking prompts requiring input

Session Becomes Unresponsive:

Use tercon_list_sessions to check session state
Use tercon_destroy_session to clean up and start fresh
Check for programs waiting for input

Debug Mode

Enable verbose logging:

export INTERACTIVE_AUTOMATION_LOG_LEVEL=DEBUG
claude code

Development Testing

# Run functionality tests
python tests/conftest.py

# Install with development dependencies
pip install -e ".[dev]"

# Run code quality checks
ruff check src/ tests/
mypy src/ --ignore-missing-imports

# Run all tests
pytest tests/

💡 Universal Examples

🔑 Agent-Controlled Interactive Examples

# Natural language commands to Claude:
"Start SSH session to prod.example.com, wait for prompts, handle authentication"
"Launch Python debugger, set breakpoints when ready, step through execution"
"Start mysql client, authenticate when prompted, then run diagnostic queries"
"Connect to docker container interactively, explore filesystem step by step"
"Launch Redis CLI, wait for connection, then check memory usage"

🚀 Terminal Program Examples

# Primary use cases - Interactive and long-running commands:
"Start session: ssh user@host"
"Launch: docker exec -it myapp bash"
"Run: kubectl exec -it pod-name -- sh"
"Debug: gdb ./myprogram"
"Profile: python -m pdb myscript.py"
"Monitor: tail -f /var/log/syslog"
"Stream: nc -l 8080"
"Connect: minicom /dev/ttyUSB0"
"Attach: tmux attach-session -t main"

# Also works with simple commands (though direct execution may be more efficient):
"Execute: ls -la /var/log"
"Run: git status"
"Check: ps aux | grep python"

🐍 Agent-Controlled Debugging

# Natural language commands to Claude:
"Start PDB debugging session, wait for prompt, then set strategic breakpoints"
"Launch debugger, examine crash point, analyze variables step by step"
"Debug Flask app interactively: set breakpoints, trace requests, inspect state"
"Attach to running process, debug live issues with agent timing control"

🔧 Complex Agent Workflows

# Natural language commands to Claude:
"SSH to server, authenticate, check services, restart if needed - handle all prompts"
"Debug crashed program: load core dump, analyze stack, suggest fixes interactively"
"Database maintenance: connect, check health, run maintenance, monitor progress"
"Deploy application: upload, configure, test, rollback if issues - handle all interactions"

🔒 Security

Agent-Controlled Design Philosophy: Maximum flexibility with user responsibility

Command filtering - Only allows secure commands (e.g., no rm -rf /)
Path restrictions - Commands run in user-specified directories, preventing unauthorized access
All commands create sessions - Both interactive and non-interactive commands create persistent sessions
Agent-controlled output - No direct output from execute_command, agents use get_screen_content
Rate limiting - 60 calls per minute to prevent abuse
Session limits - 50 concurrent sessions to prevent resource exhaustion
Comprehensive logging - Full audit trail of all operations
User responsibility - Security is managed by the user and agent, not the MCP server

📁 Project Structure

terminal-control-mcp/
├── src/terminal_control_mcp/
│   ├── main.py                 # FastMCP server with 5 MCP tools
│   ├── session_manager.py      # Terminal session lifecycle management
│   ├── interactive_session.py  # Tmux/libtmux terminal process control
│   ├── web_server.py          # FastAPI web interface with WebSocket
│   ├── security.py            # Multi-layer security validation
│   ├── models.py              # Pydantic request/response models
│   └── utils.py               # Logging and utility functions
├── tests/
│   ├── conftest.py            # Pytest fixtures and configuration
│   ├── test_security_manager.py # Security validation tests
│   ├── test_execute_command.py   # MCP tool integration tests
│   ├── test_mcp_integration.py   # End-to-end workflow tests
│   └── test_edge_cases.py        # Edge cases and error handling
├── examples/
│   └── example_debug.py       # Sample debugging script for testing
├── CLAUDE.md                  # Development guidance for AI assistants
├── README.md                  # This file
└── pyproject.toml            # Python packaging and tool configuration

🚀 Development Status

✅ Tmux Integration - Complete libtmux-based terminal control
✅ Web Interface - Real-time xterm.js with WebSocket synchronization
✅ Agent Control - 5 MCP tools for complete session lifecycle management
✅ Security Layer - Multi-layer input validation and audit logging
✅ Type Safety - Full Pydantic model validation and mypy coverage
✅ Test Coverage - 88 passing tests covering security, integration, and edge cases
✅ Code Quality - Clean architecture with black, ruff, and mypy validation
✅ 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
Add tests for new functionality
Ensure all tests pass: ruff check src/ tests/ && mypy src/ --ignore-missing-imports
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 pexpect for terminal automation

This server cannot be installed

security - not tested

license - not found

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.

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

Calculator MCP Server
QuantGeekDev
-
security
F
license
-
quality
A 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 -
32
5
TypeScript
MCP Python Toolbox
gianlucamazza
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.
Last updated -
5
Python
Claude Code MCP
auchenberg
A
security
A
license
A
quality
An 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 -
8
165
JavaScript
MIT License
my-mcp-server
15972289829
A
security
F
license
A
quality
A 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 -
340
TypeScript

View all related MCP servers