connect-to-server-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@connect-to-server-mcp check disk usage and service status on prod-web"
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.
connect-to-server-mcp
connect-to-server-mcp is a Model Context Protocol server that turns any remote machine into something an AI agent can operate. Point it at a host — bare metal, VPS, or cloud instance — with whatever credentials you have (SSH key, password, agent forwarding, or a jump host), and the agent gains a structured toolset for real operations: executing commands, reading and editing files, tailing logs, managing systemd services, and inspecting resource usage. Every action goes through explicit, permission-scoped tools with full audit logging, so the agent's reach stays exactly as wide as you allow.
Features
Any host, any auth — SSH keys (with passphrase), passwords, the local SSH agent, and jump hosts / bastions.
Per-host access modes —
read_onlyrefuses anything that looks like it mutates state;fullunlocks writes. An explicitallowed_commandsallowlist overrides both.Global guard rails —
rm -rf /,mkfs,dd of=/dev/…, fork bombs and reboots are refused on every host regardless of mode.Audit log — every attempt, including refusals, appended as JSONL.
Purpose-built tools — logs, services, and health snapshots have dedicated tools, so the agent rarely needs raw shell.
Related MCP server: remote-admin-mcp
Tools
Tool | What it does |
| List configured hosts with access mode and description |
| Re-read the inventory and drop open connections |
| Open/reuse the SSH session and report host identity |
| Run a shell command, subject to the host's policy |
| Read or overwrite a remote file over SFTP (writes make a |
| List a directory with sizes and permissions |
| Tail a log file or a systemd unit's journal, optionally filtered |
| Inspect or start/stop/restart/enable a systemd unit |
| Load, memory, disk, top processes, failed units in one call |
| Close one connection or all of them |
Install
Pick whichever fits your setup — all three end up running the same server.
1. One command (npx)
No Python setup, no clone. The launcher finds uv or Python 3.10+ on your machine, provisions what is missing, and registers the server with every Claude client it detects:
npx connect-to-server-mcp installTargets can be named explicitly, and the scope for the CLI chosen:
npx connect-to-server-mcp install claude-code --scope user
npx connect-to-server-mcp install claude-desktop
npx connect-to-server-mcp install --config-file ./.mcp.json # any MCP clientinstall also seeds a starter inventory at ~/.config/connect-to-server-mcp/hosts.yaml if you do not have one. Restart the client afterwards, then run npx connect-to-server-mcp doctor if anything looks off — it prints the runtime, config paths, and the exact command the server will be started with.
2. Claude Code plugin (marketplace)
/plugin marketplace add vstlmkh/connect-to-server-mcp
/plugin install connect-to-server@connect-to-serverThe plugin lives in plugin/ and starts the published npm package through its own launcher, so it works as soon as it is enabled — independently of which directory the client runs in.
3. Manual client config
Add this to claude_desktop_config.json (Claude Desktop) or any other MCP client:
{
"mcpServers": {
"connect-to-server": {
"command": "npx",
"args": ["-y", "connect-to-server-mcp"],
"env": { "CONNECT_MCP_CONFIG": "~/.config/connect-to-server-mcp/hosts.yaml" }
}
}
}Or register it with the Claude CLI directly:
claude mcp add connect-to-server -e CONNECT_MCP_CONFIG=~/.config/connect-to-server-mcp/hosts.yaml \
-- npx -y connect-to-server-mcpFrom source
git clone https://github.com/vstlmkh/connect-to-server-mcp.git
cd connect-to-server-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
connect-to-server-mcp # stdio transportConfigure
Copy docs/examples/hosts.yaml to ~/.config/connect-to-server-mcp/hosts.yaml, or point CONNECT_MCP_CONFIG at a file of your choosing. Any ${VAR} in the file is expanded from the environment at load time — keep secrets out of version control.
audit_log: ~/.local/state/connect-to-server-mcp/audit.jsonl
hosts:
- name: prod-web
hostname: 203.0.113.10
username: deploy
private_key: ~/.ssh/id_ed25519
known_hosts: ~/.ssh/known_hosts
mode: read_only
- name: staging
hostname: staging.internal
username: root
private_key: ~/.ssh/id_ed25519
mode: full
working_dir: /srv/appEnvironment variables the launcher understands:
Variable | Purpose |
| Path to the host inventory YAML |
| Interpreter to run the server with, bypassing uv/venv discovery |
| pip/uv spec to install instead of the published package |
Troubleshooting
sh: connect-to-server-mcp: command not found when the client starts the server.
npm refuses to run npx connect-to-server-mcp from inside a checkout of this repository: it sees the
matching name in the local package.json, assumes the binary is already provided locally, and looks for a
node_modules/.bin link that a plain clone does not have. This only affects sessions whose working
directory is the repo itself. Install globally and register that instead:
npm install -g connect-to-server-mcp
npx connect-to-server-mcp install # picks up the global binary automaticallynpx connect-to-server-mcp doctor points this out when it detects the situation. The Claude Code plugin is not affected: its launcher always spawns npm from a neutral directory.
Safety model
The policy layer is a guard rail against an agent wandering, not a security boundary. The real boundary is the remote account's own permissions: give each host a dedicated user with the narrowest sudo rules that let it do its job, and start every host in read_only until you have a reason to widen it.
Development
pytest # tests
ruff check . # lint
mypy src # typesLicense
MIT
Available Tools
12 toolscheck_connectionB
Open (or reuse) the SSH connection to a host and report basic identity.
Inputs: host (required). Returns: result
disconnectB
Close the SSH connection to one host, or to every host.
Inputs: host (required). Returns: result
list_directoryB
List a remote directory with sizes and permissions.
Inputs: host (required), path. Returns: result
list_hostsA
List every configured host with its access mode and description.
Inputs: no named parameters. Returns: result
read_fileB
Read a remote file over SFTP.
Inputs: host (required), path (required), max_bytes. Returns: result
reload_hostsA
Reload the inventory file from disk and drop all open connections.
Inputs: no named parameters. Returns: result
run_commandA
Run a shell command on a host, subject to that host's access policy.
Read-only hosts accept only inspection commands; anything that appears to modify state is refused before it reaches the server.
Inputs: host (required), command (required), timeout, working_dir. Returns: result
service_controlB
Start, stop, restart, reload, enable or disable a systemd unit.
Inputs: host (required), unit (required), action (required). Returns: result
service_statusB
Show the status of a systemd unit.
Inputs: host (required), unit (required). Returns: result
system_overviewB
Collect a health snapshot: load, memory, disk, top processes, failed units.
Inputs: host (required). Returns: result
tail_logB
Tail a log file or a systemd unit's journal.
Inputs: host (required), source (required), grep, lines. Returns: result
write_fileA
Overwrite a remote file. Refused on read-only hosts.
Inputs: host (required), path (required), content (required), backup. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Every tool targets a distinct operation: host inventory, connection lifecycle, general shell commands, file reading/writing/listing/tailing, systemd status/control, and health snapshots. Although run_command is broad, each specialized tool has a clear role and boundary, so misselection is unlikely.
Most tools use an imperative verb-noun pattern like list_hosts and read_file, but service_status, service_control, and system_overview use noun-noun forms, and disconnect is a bare verb. This mixed convention is still readable but not as predictable as a consistent pattern.
With 12 tools, the server is well-scoped for its stated purpose: inventory, connections, shell, file operations, services, and system health all have dedicated coverage. This count is neither too thin nor overly heavy.
The tool set covers core remote-host workflows: list/reload hosts, connect/disconnect, run commands, read/write/list/tail files, manage systemd services, and get a system overview. Missing capabilities like file delete/move/upload or inventory editing are generally workaroundable with run_command or external config management, so the surface is nearly complete.
Maintenance
Related MCP Connectors
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Manage remote servers, SSH terminals, files, databases and proxies with scoped access and approvals.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to securely execute remote SSH commands, perform file transfers, and monitor system status through a standardized interface. It features robust security controls including command whitelisting, blacklisting, and credential isolation to prevent unauthorized operations.1023 npmMIT
- AlicenseAqualityBmaintenanceEnables AI assistants to manage remote servers via SSH with agentless command execution, file operations, and service management.9MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to manage remote servers via SSH with 14 commands for execution, file transfer, auditing, and monitoring.18210 npm11MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to securely execute commands on remote hosts via SSH and SFTP, with persistent shells, file transfers, screenshots, and an audit log.5MIT