Terminal Control MCP server for AI agents

This MCP Terminal is a server based on the Model Context Protocol (MCP) designed specifically for integration with Large Language Models (LLMs) and AI assistants. It provides a standardized interface allowing AI to execute terminal commands and retrieve output results.

Installation

Prerequisites

Python 3.8+
uv package manager

If you haven't installed uv yet, you can install it with:

# On macOS using Homebrew
brew install uv

# On other platforms
pip install uv

Installing with uv (Recommended)

Clone the repository and install dependencies with uv:

# Clone the repository
git clone https://github.com/yourusername/mcp-terminal.git
cd mcp-terminal

# Create a virtual environment and install basic dependencies
uv venv
source .venv/bin/activate  # On Windows, use .venv\Scripts\activate
uv pip install -e .

# For iTerm2 support (macOS only)
uv pip install -e ".[iterm]"

# For development tools
uv pip install -e ".[dev]"

Note: To use the iTerm2 controller, you must enable the Python API in iTerm2 settings.

Open iTerm2, go to Preferences → General → Magic, and check the Enable Python API option.

Installing with Makefile

We provide a Makefile to simplify common operations:

# Install basic dependencies
make setup

# Install iTerm2 support
make setup-iterm

# Install development dependencies
make setup-dev

Installing with Docker

We provide Docker support for quick deployment:

# Build Docker image
docker build -t mcp-terminal .

# Run Docker container (SSE mode, port 8000)
docker run -p 8000:8000 mcp-terminal

Or using docker-compose:

# Start service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop service
docker-compose down

Usage

Running the MCP Terminal Server

There are multiple ways to start the server:

# Run directly with Python (defaults to stdio mode and auto-detected controller)
python mcp_terminal.py

# Using Makefile (stdio mode)
make run-stdio

# Using Makefile (SSE mode)
make run-sse

# Using specific controllers
make run-iterm         # Use iTerm2 controller
make run-applescript   # Use AppleScript controller
make run-subprocess    # Use Subprocess controller

Running with Docker

Run the MCP Terminal server using Docker (defaults to SSE mode and Subprocess controller):

# Run directly
docker run -p 8000:8000 mcp-terminal

# Use custom port
docker run -p 9000:8000 mcp-terminal

# Mount current directory (for local file access)
docker run -p 8000:8000 -v $(pwd):/workspace mcp-terminal

Default configuration:

Server mode: SSE
Host: 0.0.0.0 (allows remote connections)
Port: 8000
Controller: subprocess (suitable for container environments)

Using Docker Container as MCP Service in Claude or Other AI

You can configure the Docker container as an MCP service for Claude or other AI that supports MCP. Here's an example configuration for Claude:

{
  "mcp": {
    "servers": {
      "terminal": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "--mount",
          "type=bind,src=${workspaceFolder},dst=/workspace",
          "mcp-terminal",
          "mcp-terminal",
          "--mode",
          "sse",
          "--host",
          "0.0.0.0",
          "--port",
          "8000"
        ]
      }
    }
  }
}

Claude Desktop Integration Example

Here's a configuration example for Claude Desktop:

{
  "mcpServers": {
    "terminal": {
      "command": "/Users/ann/Workspace/mcp-terminal/.venv/bin/python",
      "args": [
        "/Users/ann/Workspace/mcp-terminal/mcp_terminal.py",
        "--controller",
        "subprocess"
      ]
    }
  }
}

Command Line Options

The server supports various command line options:

python mcp_terminal.py --help

Main options:

--controller or -c: Specify terminal controller type (auto, iterm, applescript, subprocess)
--mode or -m: Specify server mode (stdio, sse)
--host: Specify SSE mode host address
--port or -p: Specify SSE mode port
--log-level or -l: Specify logging level

Integration with Claude Desktop

MCP Terminal can be seamlessly integrated with Claude Desktop to provide terminal control capabilities.

Configuration Steps

Start the MCP Terminal server (in stdio mode):
```
# Run in a terminal window
make run-stdio
```
Configure Claude Desktop to use the MCP server:

Open Claude Desktop, then:
- Click the settings icon (usually in the top right)
- Navigate to the "Extensions" or "Tools" tab
- Enable the "Custom Tools" feature
- Add the MCP Terminal configuration:
  - Tool name: Terminal
  - Tool path: Enter the full path to mcp_terminal.py
  - Use stdio mode: Check this option
  - Save the configuration
Test the integration:

In your conversation with Claude, you can now ask it to execute terminal commands, such as:
- "Please list the files in my home directory"
- "Check my current Python version"
- "Create a new directory and write the current date to a file"

Troubleshooting

If the integration isn't working properly:

Ensure the MCP Terminal server is running
Check log output for errors
Verify the tool configuration in Claude Desktop is correct
Try restarting Claude Desktop and the MCP Terminal server

API Specification

MCP Terminal provides the following MCP functions:

execute_command

Executes a terminal command and retrieves the output.

Parameters:

command (string): The command to execute
wait_for_output (boolean, optional): Whether to wait for and return command output, default is true
timeout (integer, optional): Timeout in seconds for waiting for output, default is 10

Returns:

success (boolean): Whether the command was successfully executed
output (string, optional): The output of the command
error (string, optional): Error message if the command failed
return_code (integer, optional): Return code of the command
warning (string, optional): Warning message

get_terminal_info

Gets terminal information.

Parameters: None

Returns:

terminal_type (string): The type of terminal being used
platform (string): The platform it's running on

file_modify

Writes, appends, or inserts content to a file.

Parameters:

filepath (string): Path to the file
content (string): Content to write
mode (string, optional): Write mode, can be "overwrite", "append", or "insert", default is "overwrite"
position (integer, optional): Position for insertion when using "insert" mode
create_dirs (boolean, optional): Whether to create directories if they don't exist, default is true

Returns:

success (boolean): Whether the operation was successful
error (string, optional): Error message if the operation failed
filepath (string): Path to the file that was operated on
details (object, optional): Additional operation details

Security Considerations

MCP Terminal allows execution of arbitrary terminal commands, which can present security risks. When using in production environments, you should:

Limit the server to accept connections only from trusted sources
Consider implementing command whitelists or blacklists
Regularly audit executed commands
Run the server under a dedicated account with limited permissions

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.