terminal-mcp — Claude Code MCP server: what it does, setup
Gives an AI agent persistent terminal sessions for SSH, REPLs, database CLIs, and TUI apps. Useful when commands need to share state.
claude mcp add --env TERMINAL_MCP_MAX_SESSIONS=<TERMINAL_MCP_MAX_SESSIONS> --env TERMINAL_MCP_IDLE_TIMEOUT=<TERMINAL_MCP_IDLE_TIMEOUT> --transport stdio terminal-mcp -- uvx terminal-mcpWhat terminal-mcp does
terminal-mcp exposes persistent PTY sessions that remain available across tool calls. An agent can submit commands, inspect output, send keys, and interact with programs that expect a live terminal. Its tools include session_create, session_interact, session_read, session_send, session_wait_for, session_exec, and session_close.
The server supports SSH connections, Python REPL work, psql queries, TUI navigation, and waiting for a build to match a completion or error pattern. Diff reads return changed screen lines, while risky commands require confirmation. Running it through uvx requires Python 3.10+.
What it helps with
- keep an SSH connection across commands
- run code inside an interactive Python REPL
- maintain a database CLI session
- control a TUI app with key presses
- wait for a long build to finish by pattern
Example prompts for the agent
- Connect to the server over SSH, create a session labeled
prod, rundf -h, and then show the result ofdocker ps. - Open a persistent Python session, load
data.csvwith pandas, and print a summary of the table. - Start
npm run buildin a separate session and wait forBuild complete|ERRORfor up to 120 seconds.
How to install terminal-mcp
Platform CLI
claude mcp add --env TERMINAL_MCP_MAX_SESSIONS=<TERMINAL_MCP_MAX_SESSIONS> --env TERMINAL_MCP_IDLE_TIMEOUT=<TERMINAL_MCP_IDLE_TIMEOUT> --transport stdio terminal-mcp -- uvx terminal-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>
Platform CLI
codex mcp add terminal-mcp --env TERMINAL_MCP_MAX_SESSIONS=<TERMINAL_MCP_MAX_SESSIONS> --env TERMINAL_MCP_IDLE_TIMEOUT=<TERMINAL_MCP_IDLE_TIMEOUT> -- uvx terminal-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>
Config file
{
"mcpServers": {
"terminal-mcp": {
"command": "uvx",
"args": [
"terminal-mcp"
],
"env": {
"TERMINAL_MCP_MAX_SESSIONS": "<TERMINAL_MCP_MAX_SESSIONS>",
"TERMINAL_MCP_IDLE_TIMEOUT": "<TERMINAL_MCP_IDLE_TIMEOUT>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>
Config file
{
"servers": {
"terminal-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"terminal-mcp"
],
"env": {
"TERMINAL_MCP_MAX_SESSIONS": "<TERMINAL_MCP_MAX_SESSIONS>",
"TERMINAL_MCP_IDLE_TIMEOUT": "<TERMINAL_MCP_IDLE_TIMEOUT>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>
Platform CLI
gemini mcp add -e TERMINAL_MCP_MAX_SESSIONS=<TERMINAL_MCP_MAX_SESSIONS> -e TERMINAL_MCP_IDLE_TIMEOUT=<TERMINAL_MCP_IDLE_TIMEOUT> terminal-mcp uvx terminal-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about terminal-mcp
How do I install terminal-mcp in Claude Code?
Run claude mcp add terminal-mcp -- uvx terminal-mcp.
What does terminal-mcp do?
It gives an agent persistent terminal sessions for SSH, REPLs, database CLIs, TUI apps, and long-running processes.
Which session settings can terminal-mcp use?
Set the session limit and idle period with TERMINAL_MCP_MAX_SESSIONS and TERMINAL_MCP_IDLE_TIMEOUT.
