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_only refuses anything that looks like it mutates state; full unlocks writes. An explicit allowed_commands allowlist 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

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 install

Targets 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 client

install 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-server

The plugin ships its own .mcp.json, so the server appears as soon as it is enabled.

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-mcp

From 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 transport

Configure

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/app

Environment variables the launcher understands:

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        # types

License

MIT