home / mcp / mcp terminal mcp server

MCP Terminal MCP Server

MCP Terminal Server - Interactive terminal sessions via Model Context Protocol

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "alejoair-mcp-terminal": {
      "url": "http://localhost:8777/mcp",
      "headers": {
        "MCP_TERMINAL_HOST": "0.0.0.0",
        "MCP_TERMINAL_PORT": "8777",
        "MCP_TERMINAL_LOG_LEVEL": "debug"
      }
    }
  }
}

You can run an interactive terminal server that exposes real PTY sessions through MCP and REST, letting you control, automate, and observe terminal sessions from AI assistants or remote clients across platforms.

How to use

Start by running the MCP Terminal Server locally to expose terminal sessions over MCP and REST. You can create multiple terminal sessions, send input, resize, capture visual snapshots, and close sessions from your MCP client. Use the MCP endpoint to access terminal endpoints and manage sessions from your automation tools.

How to install

Prerequisites: Python and pip must be available on your system.

Install the MCP Terminal package from PyPI.

pip install mcp-terminal

Additional sections

Configuration notes help you tailor the server for development or production use. You can bind to a specific host and port, enable auto-reload for development, and adjust logging levels.

Runtime examples show how to start and access the server. The default port is 8777, but you can override it with command line options. For example, to start on port 8777 and be accessible on all interfaces, you would run the same command without extra options or specify a host.

mcp-terminal
```

```
mcp-terminal --port 9000
```

```
mcp-terminal --host 0.0.0.0 --port 8888

Troubleshooting and notes

If you need to adjust where the server runs or how it is exposed, use the host and port options. When running behind a reverse proxy, ensure the proxy forwards the MCP endpoint at /mcp and the REST API at /docs.

MCP endpoints and usage patterns

You can create terminal sessions, send commands, retrieve visual snapshots, resize, and close terminals. Use an MCP client to interact with these endpoints in a structured, tool-like fashion.

Available tools

create_terminal_terminals__post

Create a new terminal session with specified rows and cols. Returns a terminal_id that you will use for subsequent actions.

list_terminals_terminals__get

List all active terminal sessions with their IDs and statuses.

get_terminal_snapshot_terminals__terminal_id__snapshot_get

Fetch a visual snapshot of the terminal display, including cursor position and size.

send_terminal_input_terminals__terminal_id__input_post

Send input to a specific terminal session to run commands or interact with the shell.

resize_terminal_terminals__terminal_id__resize_put

Resize the terminal session by adjusting rows and columns.

close_terminal_terminals__terminal_id__delete

Close and terminate a terminal session.