SSH Session MCP
Gives Claude a persistent SSH terminal session instead of running each command in a new shell. The AI and human share one PTY with a browser viewer, input locking to prevent concurrent typing, and async tracking for long-running remote work. Includes safe and full execution modes with policy rules for risky commands, plus multi-device profiles and a local debug mode. Built for embedded boards, ROS hosts, and remote dev servers where you need real terminal state and want to watch or intervene when Claude runs commands. Ships via npx for MCP clients or as a Docker container for deployment scenarios.
- GitHub stars
- 2
- tools
- 23
- auth
- Secret needed
- transport
- STDIO
- env vars
- 13
- last updated
- May 15, 2026
Tools
23 toolsPublic tool metadata for what this MCP can expose to an agent.
ssh-quick-connectOne-step connect flow for agents
One-step connect flow for agents
No parameter schema in public metadata yet.
ssh-runMain command execution tool
Main command execution tool
No parameter schema in public metadata yet.
ssh-statusRuntime overview
Runtime overview
No parameter schema in public metadata yet.
ssh-command-statusAsync poller
Async poller
No parameter schema in public metadata yet.
ssh-retryRetry executor
Retry executor
No parameter schema in public metadata yet.
ssh-session-policy-listShow inherited policy defaults and the current session rule set
Show inherited policy defaults and the current session rule set
No parameter schema in public metadata yet.
ssh-session-policy-upsertAdd or update a session-specific custom policy rule
Add or update a session-specific custom policy rule
No parameter schema in public metadata yet.
ssh-session-policy-removeRemove a session-specific custom policy rule
Remove a session-specific custom policy rule
No parameter schema in public metadata yet.
ssh-session-policy-resetRestore inherited rules for the current session
Restore inherited rules for the current session
No parameter schema in public metadata yet.
ssh-session-openOpen a session with explicit SSH parameters
Open a session with explicit SSH parameters
No parameter schema in public metadata yet.
ssh-session-sendSend raw PTY input
Send raw PTY input
No parameter schema in public metadata yet.
ssh-device-listList configured devices and defaults
List configured devices and defaults
No parameter schema in public metadata yet.
ssh-session-readRead buffered terminal output by offset
Read buffered terminal output by offset
No parameter schema in public metadata yet.
ssh-session-watchLong-poll for output and dashboard changes
Long-poll for output and dashboard changes
No parameter schema in public metadata yet.
ssh-session-historyRead line-numbered mixed terminal history
Read line-numbered mixed terminal history
No parameter schema in public metadata yet.
ssh-session-controlSend control keys such as ctrl_c, arrows, or tab
Send control keys such as ctrl_c, arrows, or tab
No parameter schema in public metadata yet.
ssh-session-resizeResize the PTY
Resize the PTY
No parameter schema in public metadata yet.
ssh-session-listList tracked sessions
List tracked sessions
No parameter schema in public metadata yet.
ssh-session-diagnosticsInspect lock state, warnings, running command state, and viewer health
Inspect lock state, warnings, running command state, and viewer health
No parameter schema in public metadata yet.
ssh-session-set-activeChoose the default session
Choose the default session
No parameter schema in public metadata yet.
ssh-viewer-ensureOpen or reuse the local viewer
Open or reuse the local viewer
No parameter schema in public metadata yet.
ssh-viewer-listList tracked viewer processes
List tracked viewer processes
No parameter schema in public metadata yet.
ssh-session-closeClose a session cleanly
Close a session cleanly
No parameter schema in public metadata yet.
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageConfiguration
SSH_MCP_CONFIGOptional explicit path to ssh-session-mcp.config.json when the config is not in the current working directory.
SSH_MCP_INSTANCEOptional runtime instance id used to isolate state across multiple MCP clients or agents.
VIEWER_PORTViewer HTTP port. Use auto to allocate a free local port, or 0 to disable the browser viewer.
VIEWER_HOSTOptional viewer bind host. Defaults to 127.0.0.1 for local-only browser access.
AUTO_OPEN_TERMINALSet to true or 1 to automatically open the browser terminal when a session is created.
SSH_MCP_MODEOperation mode. safe blocks risky or unsuitable terminal actions by default, while full allows broader execution.
SSH_MCP_LOCALSet to true or 1 to run a local shell instead of opening a real SSH connection. Useful for demos and offline testing.
SSH_MCP_DEBUGSet to true or 1 to expose browser-side debug controls intended for demos and local troubleshooting.
SSH_HOSTLegacy single-target SSH host when not using ssh-session-mcp.config.json device profiles.
SSH_PORTLegacy single-target SSH port when not using ssh-session-mcp.config.json device profiles.
SSH_USERLegacy single-target SSH username when not using ssh-session-mcp.config.json device profiles.
SSH_PASSWORDsecretOptional legacy password-based SSH authentication value.
SSH_KEYOptional path to a local SSH private key file for legacy single-target mode.
Readme
ssh-session-mcp
中文 | English
Persistent shared-terminal runtime for MCP clients over SSH.
ssh-session-mcp gives the user and the AI the same SSH PTY session, adds a browser viewer, tracks who typed what, and makes long-running remote work manageable instead of stateless.
Contents
Details
- Repository
- github.com/zw-awa/ssh-session-mcp
- Website
- zw-awa.github.io/ssh-session-mcp
- Package
ssh-session-mcp- Transport
- STDIO
- Auth
- Required
- Registry
- MCP registry, active