Interminal
Lightweight MCP server providing terminal access (SSH & local shells) for AI assistants.
Open source Open in the app JSON README (API)
About
Lightweight MCP server providing terminal access (SSH & local shells) for AI assistants.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- qiuwenzheng
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.4
- Stars
- 3
- Last push
- 2026-07-13T04:46:30Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:11
- Updated
- 2026-08-29 03:02:11
- Origin id
io.github.QiuwenZheng/interminal
README
# Interminal
<!-- mcp-name: io.github.QiuwenZheng/interminal -->
Lightweight MCP server that gives AI assistants terminal access — SSH and local shells — with support for interactive and long-running commands.
## Installation
```bash
# Run directly, no install needed (recommended)
uvx mcp-interminal
# Or install permanently
pip install mcp-interminal
```
Requires Python ≥ 3.11.
## MCP Client Configuration
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"interminal": {
"command": "uvx",
"args": ["mcp-interminal"]
}
}
}
```
**Cursor / other clients**: same `command` + `args` format above.
## Tools
| Tool | Description |
|------|-------------|
| `connect_ssh` | Connect to an SSH server; returns `session_id` and welcome banner |
| `execute` | Run a command locally (no session needed) or over SSH; returns output or `status=partial` + `command_id` |
| `read_output` | Poll a running command for new output without sending input |
| `respond` | Send text input to a command waiting at a prompt |
| `send_control` | Send control keys: `ctrl+c`, `ctrl+z`, arrow keys, F-keys, etc. |
| `disconnect` | Close an SSH session and release all resources |
## Persistent State
Each `execute` call runs in an isolated channel — there is no persistent shell between calls. For simple tasks, chaining with `&&` works.
For **multi-step workflows** (project development, debugging, deployment), a terminal multiplexer (like Zellij) provides persistent state that survives across calls. The AI agent can create a persistent session where `cd`, environment variables, virtual environments, and long-running processes carry over naturally.
## Key Behaviors
- **Stateless execute** — each call is an isolated channel; `cd /foo` does not persist. Simple tasks: chain with `&&`. Multi-step workflows: use a terminal multiplexer.
- **Long-running commands** return `status="partial"` with a `command_id`; poll with `read_output` or send input with `respond`
- **SSH PTY** is 500×200 xterm-256color so multiplexer sessions render at your actual terminal size
## Optional Dependencies
```bash
pip install "mcp-interminal[pty]" # Windows PTY support (pywinpty)
pip install "mcp-interminal[ansi]" # ANSI escape rendering (pyte)
pip install "mcp-interminal[pty,ansi]" # both
```