mcpterm

What is mcpterm?

mcpterm is an MCP tool server that provides stateful, TUI‑compatible terminal sessions. It is a proof‑of‑concept built with mcp‑go and works well with Claude Desktop.

How to use mcpterm?

Clone the repository, run make to generate the bin/mcpterm binary, and move it to a directory in your PATH (e.g., /usr/local/bin/mcpterm). Then add it as an MCP server in your claude_desktop_config.json with the command "mcpterm" and no arguments, then restart Claude Desktop.

Key features of mcpterm

• 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).

Use cases of mcpterm

• Running a series of commands that depend on previous directory changes or environment variables.
• Interacting with TUI applications such as vim or a Python REPL through Claude.
• Writing a Dockerfile in vim, then building and running the container in the same session.
• Executing commands inside a container from a stateful shell session.
• Combining multiple command‑line tools in a persistent workspace via Claude.

FAQ from mcpterm

What tools does mcpterm provide?

mcpterm provides two tools: run for running a command in a stateful terminal session, and runScreen for running a command or series of keystrokes and returning the screen output.

How do I install mcpterm?

Clone the repository (git clone https://github.com/dwrtz/mcpterm.git), run make to build the binary, and move bin/mcpterm to a directory in your PATH (e.g., sudo mv bin/mcpterm /usr/local/bin/mcpterm).

Which MCP client is mcpterm compatible with?

The README states it works quite well with Claude Desktop. No other clients are mentioned.

What control sequences are supported for the runScreen tool?

The README lists common control sequences such as ^C (Ctrl+C), ^D (Ctrl+D), ^Z (Ctrl+Z), ^[ (Escape), ^H (Backspace), ^M (Carriage return), and others. These are passed as hex codes (e.g., "\x03" for Ctrl+C).

Can mcpterm be used with non‑TUI commands?

Yes, the run tool executes any command in a stateful session, and the runScreen tool can also be used for non‑TUI commands, though it is intended for TUI apps.