Terminal Control

🚀 MCP Terminal Project Documentation

The MCP Terminal is a terminal control server that enables integration with large language models via the MCP protocol, facilitating the execution and management of terminal commands.

✨ Features

• Support for Multiple Terminal Controllers: It includes controllers based on subprocesses, AppleScript, and the iTerm2 API.
• Standard MCP Interface: Facilitates interaction with other systems and services.
• Scalable Architecture: Supports the addition of new terminal controllers and functional modules.
• Secure Design: Equipped with permission control and command filtering mechanisms to ensure the security of the operating environment.

📦 Installation

Prerequisites

1. Operating System: Linux or macOS
2. Python Version: 3.6 or higher
3. Dependency Management Tool: It is recommended to use pip for package management.

Installation with uv

uv mcp-terminal@latest

Installation with Makefile

make install

🚀 Quick Start

Start the Server

Run the following command to start the MCP Terminal server:

python -m src.mcp_terminal.stdiostream_server

💻 Usage Examples

Execute Terminal Commands

# Basic Usage
mcp-terminal execute_command --command "ls"

# Command Execution with Timeout Settings
mcp-terminal execute_command --command "sleep 10" --timeout 5

📚 Configuration for Claude Desktop

Tool Configuration

Add the MCP Terminal tool in Claude Desktop:

{
  "tools": {
    "mcp-terminal": {
      "type": "execute_command",
      "config": {
        "host": "localhost",
        "port": "1234"
      }
    }
  }
}

🛠️ Troubleshooting

Common Issues

• Issue: Unable to connect to the MCP Terminal server.

  • Solution: Check if the server is running and ensure the network configuration is correct.

• Issue: Command execution times out.

  • Solution: Increase the command waiting timeout or optimize the performance of the called command.

📄 API Specification

Execute a Command

execute_command(
    command: str,
    wait_for_output: bool = True,
    timeout: int = 10
) -> dict

Parameter Explanation:

• command: The terminal command to be executed.
• wait_for_output: Whether to wait for the command output, default is True.
• timeout: The waiting timeout in seconds, default is 10.

Return Value:

{
  "success": bool,
  "output": str,
  "error": str,
  "return_code": int,
  "warning": str
}

Get Terminal Information

get_terminal_info() -> dict

Return Value:

{
  "terminal_type": str,
  "platform": str
}

🔒 Security Precautions

• Permission Control: Only allow trusted sources to connect to the MCP Terminal server.
• Command Filtering: It is recommended to implement a command whitelist or blacklist mechanism to prevent unauthorized operations.
• Audit Logs: Regularly review the historical command execution records.

🛠️ Development Guide

Directory Structure

Project Root/
├── mcp_terminal.py          # Entry script
├── pyproject.toml           # Project configuration and dependency management
├── README.md                # User documentation
├── Makefile                 # Build and run script
└── src/
    ├── __init__.py
    └── mcp_terminal/
        ├── stdio_server.py   # Standard input/output server implementation
        ├── controllers/      # Terminal controller module
        │   ├── base.py       # Basic interface definition
        │   ├── subprocess.py  # Subprocess controller implementation
        │   ├── applescript.py # AppleScript controller implementation
        │   └── iterm.py      # iTerm2 API controller implementation
        └── tools/            # Tool module
            └── terminal_tools.py  # Terminal operation utility functions

Contribution Guidelines

1. Code Style: Follow the PEP8 coding standard.
2. Testing Requirements: Add unit tests and integration tests for new features.
3. Submission Process:
   • Check the code format before submission.
   • The submission message should include a description of the relevant changes.

📞 Contact Information

• Email: support@mcp-terminal.com
• GitHub: https://github.com/mcpteam/mcp-terminal