Terminal Control MCP Server

A modern FastMCP-based server that enables Claude Code to control terminal programs through agent-directed interaction. Built with the latest MCP Python SDK 1.12.0, this server provides intelligent terminal session management for all types of commands - from simple utilities like ls and git status to complex interactive programs like SSH sessions, database connections, interactive installers, and debugging workflows.

✨ Features

🏗️ Modern FastMCP Architecture

• ⚡ FastMCP Framework: Built with MCP Python SDK 1.12.0 for optimal performance
• 🔧 Decorator-Based Tools: Clean @mcp.tool() decorators with automatic schema generation
• 📝 Pydantic Models: Type-safe input/output validation with structured data support
• 🎯 Automatic Schema Generation: JSON schemas generated from Python type hints
• 🔄 Lifespan Management: Proper startup/shutdown with resource cleanup

🚀 Agent-Controlled Terminal Interaction

• 🎯 Agent-Controlled Interaction: Agents have full control over timing and interaction flow
• 📊 Session Management: Maintain persistent sessions with manual cleanup
• 🔍 Real-time Screen Content: Get current terminal output with timestamps
• 🌐 Web Interface: Direct browser access to terminal sessions for manual interaction
• 🛡️ Simple Design: No complex automation patterns - agents decide when to act
• 🐛 Universal Terminal Support: Control ANY terminal program (interactive and non-interactive)
• 🔒 User-Controlled Security: Maximum flexibility with user responsibility

💪 Performance & Reliability

• 📦 Minimal Dependencies: Only essential dependencies for terminal interaction
• ⚡ Fast Installation: Lightweight package with minimal footprint
• 🛡️ Type Safety: Full type coverage with mypy and Pydantic validation
• 🧹 Clean Code: Modern Python with black formatting and ruff linting
• ⏱️ Smart Timeouts: Process startup timeouts only - agents control interaction timing

🚀 Quick Start

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)

1. Install the package first (required for console script):

   # Install the package to create the console script
   pip install .
   

2. 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
   

3. 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

1. 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": {
       "interactive-automation": {
         "command": "/path/to/terminal-control-mcp/.venv/bin/python",
         "args": ["-m", "terminal_control_mcp.main"],
         "cwd": "/path/to/terminal-control-mcp"
       }
     }
   }
   

2. Alternative configuration using console script:

   {
     "mcp.servers": {
       "interactive-automation": {
         "command": "/path/to/terminal-control-mcp/.venv/bin/terminal-control-mcp",
         "cwd": "/path/to/terminal-control-mcp"
       }
     }
   }
   

3. 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:

1. Call tercon_get_screen_content to see current terminal state
2. Analyze screen content and timestamp
3. Decide whether to wait longer or take action
4. 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:

1. tercon_execute_command - Creates session and starts process
2. tercon_get_screen_content - Agent sees current terminal state (output or interface) with timestamp
3. tercon_send_input - Agent sends input if process is waiting for interaction
4. Repeat steps 2-3 as needed (agent controls timing)
5. 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 interactive-automation -s user interactive-automation-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:
1. Claude: "I've started a Python debugger session. You can also access it directly at http://localhost:8080/session/session_abc123"
2. User opens the URL in browser
3. User sees live terminal output and can type commands directly
4. Both agent and user can interact with the same session simultaneously

Monitoring Long-Running Processes

# For monitoring builds, deployments, or long-running scripts:
1. Agent starts process: "Starting your build process..."
2. User opens web interface to monitor progress in real-time
3. User can send manual commands if needed (like stopping the process)
4. 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

[UPDATE THIS!]

🚀 Development Status

• ✅ FastMCP Architecture - Modern MCP Python SDK 1.12.0 implementation
• ✅ Agent-Controlled Design - Simplified architecture with agent timing control
• ✅ Type Safety - Full Pydantic model validation and mypy type coverage
• ✅ Minimal Dependencies - Only essential dependencies for terminal interaction
• ✅ Comprehensive Security - Security controls with user/agent responsibility
• ✅ Clean Architecture - Well-organized, maintainable code with modern tooling
• ✅ Universal Terminal Support - Works with ANY terminal program
• ✅ Code Quality - All linting (ruff) and type checking (mypy) passes

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: ruff check src/ tests/ && mypy src/ --ignore-missing-imports
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

🙏 Acknowledgments

• Built on the Model Context Protocol (MCP) by Anthropic
• Uses pexpect for terminal automation