Mcpterm

🚀 mcpterm Introduction

mcpterm is an MCP tool server that offers stateful and TUI-compatible terminal sessions.

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

It works well when used with Claude Desktop.

🚀 Quick Start

📦 Installation

Clone the repository and run make to generate bin/mcpterm:

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

Move the mcpterm binary file to a directory in your PATH:

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

💻 Usage Examples

Add to Claude Desktop

Edit your claude_desktop_config.json file (on Mac, it's located at ~/Library/Application Support/Claude/claude_desktop_config.json):

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

Restart Claude Desktop. Now, Claude should be able to see the two tools provided by mcpterm.

✨ Features

Tool Explanation

• run: Run commands in a stateful terminal session. For example, if you change to a certain directory, subsequent commands will be executed in that directory.
• runScreen: Run commands or a series of key presses and return the screen output. It's mainly used for TUI applications like vim or the Python REPL.

Usage Tips

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

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

Although it's not perfect, it's quite useful. Claude can use vim to write a Dockerfile, then run a container and enter an interactive session, and then execute commands in the container, such as starting a Python REPL session.