Interactive Automation MCP Server

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

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

Remote/Network Access

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

Essential Tool Examples

Basic Commands

Interactive Programs

Complex Workflows

🌐 Web Interface Usage Examples

Direct Terminal Access

Monitoring Long-Running Processes

🐛 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

Claude will start the Python debugger and show you:

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

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

Finding the Bug

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

Investigating Variables

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

Understanding the Problem

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

Wrapping Up

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:

Development Testing

💡 Universal Examples

🔑 Agent-Controlled Interactive Examples

🚀 Terminal Program Examples

🐍 Agent-Controlled Debugging

🔧 Complex Agent Workflows

🔒 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

🚀 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