Which integrations are available for this server?

Enables port forwarding to expose a remote PostgreSQL server locally, allowing local clients to connect to the remote database. Commands are run inside a tmux session, allowing users to attach and observe command execution in real-time.

How do I use Agent SSH MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Agent SSH MCP start session with my-server and run 'df -h'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Agent SSH MCP

by xcdd

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

Agent SSH MCP

MCP server for persistent SSH sessions with tmux integration, port forwarding, and SFTP file writes — built for AI agent workflows.

Based on ssh-mcp-sessions by Justin Fry (MIT), with significant enhancements for agent reliability.

What's improved over the original

The original fryjustinc/ssh-mcp-sessions provides 8 basic tools that execute commands directly in a hidden ssh2 shell buffer. This repo is a significant rework:

Architecture changes

Original	This repo
Commands run in a hidden ssh2 shell; output captured via in-memory buffer	Commands run inside a tmux session (`ai`); user can attach and watch live with `tmux attach -t ai`
Single end marker: `printf '__MCP_DONE__%s%d\n' $?` — no start marker, no polling	Dual start+end markers polled via `capture-pane`; output extracted between them
No reconnect logic — connection loss kills the session	Auto-reconnects on next command; keepalive every 30 s
No file transfer	SFTP: `upload-file`, `download-file`, `write-remote-file`
No port forwarding	`forward-port` / `stop-forward` via ssh2 `forwardOut`

New tools added

Tool	Purpose
`setup-tmux`	(Re)initialize tmux on an existing session
`upload-file`	Upload local file to remote via SFTP
`download-file`	Download remote file to local via SFTP
`write-remote-file`	Write text content directly via SFTP — no shell, no quoting issues, no heredoc
`forward-port`	Forward a local TCP port to a remote host:port
`stop-forward`	Stop a port forward tunnel

Reliability fixes

Issue	Root cause	Fix
Captured output contained entire pane history	End marker regex required a preceding `\n`; commands without trailing newline caused marker detection to fail → 30 s timeout → full pane returned as fallback	Regex changed to `endMarker(\d+)(?:\n
Long sessions accumulated large scrollback, slowing polling	`capture-pane -S -1000` scanned 1000 lines on every poll	`tmux clear-history` before each command + window reduced to `-S -200`
heredoc (`<< EOF`) hung the session	tmux waits for EOF input that never arrives	Detected and rejected with a helpful error
exit code `-1` was indistinguishable from a real command failure	Timeout and true failure both returned the same code	Timeout now returns `[tmux capture timed out — command may still be running]`

Related MCP server: ssh-mcp

Installation

npm install -g agent-ssh-mcp

Or run without installing:

npx agent-ssh-mcp

MCP Client Configuration

Add to your MCP client config (Claude Desktop, Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["agent-ssh-mcp"]
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

Claude Code / VS Code — .vscode/settings.json:

{
  "claude.mcpServers": {
    "ssh": { "command": "npx", "args": ["agent-ssh-mcp"] }
  }
}

Cursor — ~/Library/Application Support/Cursor/mcp.json (macOS)

Host Configuration

Hosts are stored in ~/.ssh-mcp/hosts.json, created automatically on first use.

Add a host

{
  "tool": "add-host",
  "host_id": "my-server",
  "host": "1.2.3.4",
  "port": 22,
  "username": "root",
  "password": "optional",
  "keyPath": "~/.ssh/id_rsa"
}

Authentication priority: password → private key → SSH agent (SSH_AUTH_SOCK).

Tools Reference

Session lifecycle

Tool	Parameters	Description
`add-host`	`host_id`, `host`, `port`, `username`, `password?`, `keyPath?`	Save SSH host config
`list-hosts`	—	List all saved hosts
`edit-host`	`host_id` + any field to change	Update host config
`remove-host`	`host_id`	Delete host config
`start-session`	`host_id`, `sessionId?`	Connect and auto-initialize tmux
`list-sessions`	—	Show active sessions with uptime
`close-session`	`sessionId`	Disconnect and clean up
`setup-tmux`	`session_id`	(Re)initialize tmux on an existing session

Command execution

Tool	Parameters	Description
`exec`	`session_id`, `command`	Run a command; auto-routes through tmux when available

Note: Do not use tmux send-keys manually — exec handles tmux routing automatically.

Avoid heredoc syntax (<< EOF). Use write-remote-file instead.

File transfer

Tool	Parameters	Description
`upload-file`	`session_id`, `local_path`, `remote_path`	Upload local file via SFTP (preferred for large/binary files)
`download-file`	`session_id`, `remote_path`, `local_path`	Download remote file via SFTP
`write-remote-file`	`session_id`, `remote_path`, `content`	Write text content directly via SFTP — handles special characters, no shell quoting issues

Port forwarding

Tool	Parameters	Description
`forward-port`	`session_id`, `local_port`, `remote_host`, `remote_port`, `tunnel_id?`	Forward `127.0.0.1:<local_port>` → `<remote_host>:<remote_port>`
`stop-forward`	`tunnel_id`	Stop a port forward tunnel

Example — access a remote PostgreSQL locally:

{
  "tool": "forward-port",
  "session_id": "my-session",
  "local_port": 15432,
  "remote_host": "127.0.0.1",
  "remote_port": 5432
}

Then connect to postgresql://user:pass@127.0.0.1:15432/db.

Typical Agent Workflow

1. add-host       → save target server
2. start-session  → SSH connect + tmux init (returns session_id)
3. exec           → run commands (output is clean, no scrollback pollution)
4. write-remote-file / upload-file → write files reliably
5. forward-port   → expose remote services locally if needed
6. close-session  → clean up

Sessions auto-close after 2 hours of inactivity.

tmux Observability

Every command is executed inside a tmux session named ai. You (or the user) can attach to watch in real time:

ssh root@<host>
tmux attach -t ai

Building from Source

git clone https://github.com/xcdd/Agent-SSH-MCP
cd Agent-SSH-MCP
npm install
npm run build

Run tests:

npm test

Security Notes

~/.ssh-mcp/hosts.json may contain passwords — treat it as sensitive (chmod 600).
Prefer key-based or SSH agent authentication.
Sessions inherit all privileges of the SSH user.

License

MIT — see LICENSE.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
ClawLinkOAuth
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24

Related MCP Servers

mcp-remote-ssh
Command Line Shell Access
faizbawa
A
license
A
quality
A
maintenance
MCP server giving AI agents full SSH access with persistent sessions, structured command output, SFTP file transfer, and port forwarding.
Updated a month ago (2026-08-17 06:29 UTC)
18
10
MIT
ssh-mcp
Shell Access Command Line
slepp
A
license
A
quality
C
maintenance
An MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.
Updated 2 months ago (2026-07-09 00:20 UTC)
17
168 PyPI
22
MIT
mcp-ssh-interactive
Shell Access Command Line
qnxqnxqnx
A
license
Not graded
quality
D
maintenance
MCP server that enables AI agents to run fully interactive SSH sessions (via tmux) and execute commands like a human operator, with persistent sessions and multiple concurrent connections.
Updated 10 months ago (2025-11-05 08:10 UTC)
6
MIT
R-Shell
Shell Access File Systems Command Line
MageGojo
A
license
Not graded
quality
B
maintenance
MCP server enabling AI assistants to securely operate remote servers via persistent SSH sessions, with tools for command execution, file transfer, directory listing, and system monitoring.
Updated a month ago (2026-08-10 08:47 UTC)
4
MIT

Agent SSH MCP

What's improved over the original

Architecture changes

New tools added

Reliability fixes

Installation

MCP Client Configuration

Host Configuration

Add a host

Tools Reference

Session lifecycle

Command execution

File transfer

Port forwarding

Typical Agent Workflow

tmux Observability

Building from Source

Security Notes

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-remote-ssh

ssh-mcp

mcp-ssh-interactive

R-Shell