Terminal Session

by dwrtz

2 stars

231 downloads

Not rated

GitHub

About

Provides stateful, TUI-compatible terminal sessions for executing commands and running interactive applications, enabling persistent interaction with command-line interfaces and programs.

Details

Author: dwrtz
Repository: dwrtz/mcpterm
GitHub stars: 2
Downloads: 231
Categories: AI, Design, Developer Tools, File Management, Infrastructure, Frontend, Other

- Stateful terminal sessions (subsequent commands share the same shell state).
- TUI‑compatible screen output via the runScreen tool.
- Two distinct tools: run (stateful command execution) and runScreen (return screen output for TUI apps).
- Integrates with Claude Desktop out of the box.
- Supports control sequences for interacting with terminal apps (e.g., vim, python REPL).

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Terminal Session

Command (node, npx, python, etc.) mcpterm

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

From the repository

Clone the repo and run make to generate bin/mcpterm.

git clone https://github.com/dwrtz/mcpterm.git
cd mcpterm
make

Move the mcpterm binary to a directory in your PATH.

sudo mv bin/mcpterm /usr/local/bin/mcpterm

`run`

Runs a command in a stateful terminal session. Subsequent commands will execute in the same directory context.

`runScreen`

Runs a command or series of keystrokes and returns the screen output. Intended for TUI applications such as vim or a python REPL.

run: Runs a command in a stateful terminal session. E.g. if you cd into a directory, subsequent commands will run in that directory.

runScreen: Runs a command or series of keystrokes and returns the screen output. Intended for TUI apps such as vim or a python REPL.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "terminal session": {
            "cwd": "string (optional)",
            "env": {},
            "args": [],
            "shell": false,
            "command": "mcpterm"
        }
    }
}

Linux

{
    "cwd": "string (optional)",
    "env": [],
    "args": [],
    "shell": false,
    "command": "mcpterm"
}

Macos

{
    "cwd": "string (optional)",
    "env": [],
    "args": [],
    "shell": false,
    "command": "mcpterm"
}

Windows

{
    "cwd": "string (optional)",
    "env": [],
    "args": [],
    "shell": false,
    "command": "mcpterm"
}

mcpterm

An MCP tool server that provides stateful, TUI-compatible terminal sessions.

This is a proof-of-concept using mcp-go.

Works quite well with Claude Desktop.

Usage

Clone the repo and run make to generate bin/mcpterm.

git clone https://github.com/dwrtz/mcpterm.git
cd mcpterm
make

Move the mcpterm binary to a directory in your PATH.

sudo mv bin/mcpterm /usr/local/bin/mcpterm

Add to Claude Desktop

Edit your claude_desktop_config.json (on Mac it's in ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcpterm": {
      "command": "mcpterm",
      "args": []
    }
  }
}

Restart Claude Desktop. Now Claude should see the 2 tools provided by mcpterm.

Tools

run: Runs a command in a stateful terminal session. E.g. if you cd into a directory, subsequent commands will run in that directory.

runScreen: Runs a command or series of keystrokes and returns the screen output. Intended for TUI apps such as vim or a python REPL.

Tips:

You may want to tell Claude to use following control sequences with the runScreen tool:

"^X": "\x18", // Ctrl+X
"^O": "\x0F", // Ctrl+O
"^J": "\x0A", // Enter
"^C": "\x03", // Ctrl+C
"^D": "\x04", // Ctrl+D
"^Z": "\x1A", // Ctrl+Z
"^[": "\x1B", // Escape
"^H": "\x08", // Backspace
"^M": "\x0D", // Carriage return
"^L": "\x0C", // Form feed
"^G": "\x07", // Bell
"^U": "\x15", // Clear line
"^W": "\x17", // Delete word
"^Y": "\x19", // Paste from kill buffer
"^V": "\x16", // Literal input
"^K": "\x0B", // Kill line
"^E": "\x05", // End of line
"^A": "\x01", // Beginning of line
"^I": "\x09", // Tab

While not perfect, it works pretty well. Claude is able to use vim to write a Dockerfile, then run the container in an interactive session, then run commands in the container such as a python REPL.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Terminal Session

About

Details

Jump to

Setting up with Highlight

Setting up with Cursor

JSON

JSON

JSON

Setting up with Claude Desktop

JSON

JSON

JSON

Setting up with Windsurf

JSON

JSON

JSON

Setting up with Cline

JSON

JSON

JSON

Setting up with Goose

JSON

JSON

JSON

From the repository

`run`

`runScreen`

Claude Desktop / Cursor

Linux

Macos

Windows

mcpterm

Usage

Add to Claude Desktop

Tools

Tips:

Install

About

Details

Jump to

Setting up with Highlight

From the repository

run

runScreen

Claude Desktop / Cursor

Linux

Macos

Windows

mcpterm

Usage

Add to Claude Desktop

Tools

Tips:

Install

More like this

Sentry

Github

Git

GitLab

Context 7

1Panel

`run`

`runScreen`