@mindstone/mcp-server-replit-ssh

@mindstone/mcp-server-replit-ssh

Replit SSH MCP server — read, write, list, search, stat, move, and delete files on Replit projects over SSH/SFTP, plus one-shot generation of the local SSH key and ~/.ssh/config block.

Local Replit SSH MCP. Connects from the operator's machine to *.replit.dev hosts only, writes are atomic with SHA-256 read-back, and the ~/.ssh/config rewrite parses via AST rather than Match exec shell evaluation.

Status

• Version: 0.2.0 · npm
• Auth: Local SSH key on disk (~/.ssh/rebel-replit by default; resolved via ~/.ssh/config IdentityFile if set). No env-var-supplied secrets.
• Tools: 9 (connection, files, ssh-setup)
• Surface: local-protocol
• Machine-readable: STATUS.json

Why this exists

Replit ships a hosted "Agent" experience but does not publish an MCP server for the SSH/SFTP surface its Core users get. The community options at the time we built this either shelled out to the system ssh binary (so connection failures surfaced as generic non-zero exit codes) or parsed ~/.ssh/config with the upstream ssh-config@5.1.0 package, which evaluates Match exec "<cmd>" blocks by running them through the shell — that is local code execution against any consumer that reads a user-controlled config file. We wrote our own so that the host application can read, list, and atomically write files on a Replit project from the operator's own machine, with a host allow-list pinned to *.replit.dev, a safe AST-only config evaluator, SHA-256 read-back verification on every write, and a structured recovery contract on every tool error.

Example interaction

"List the files in my Replit project, then read package.json and tell me which scripts are defined."

Tools the host calls:

• replit_check_connection — verifies SSH connectivity and SFTP support, returns latency.
• replit_list_files — lists files and directories at ..
• replit_read_file — reads package.json from the project root as UTF-8 text.

Response (trimmed):

{
  "ok": true,
  "files": [
    { "name": "package.json", "type": "file", "size": 612 },
    { "name": "src", "type": "directory" }
  ],
  "package": {
    "scripts": {
      "dev": "node src/index.js",
      "test": "vitest run"
    }
  }
}

Requirements

• Node.js 20+
• npm
• A Replit account with SSH access (Replit Core or higher)
• A live *.replit.dev host from a Replit project (open the project, click SSH → Connect → Connect manually, copy the host and username)
• An SSH key registered with Replit at replit.com/account#ssh-keys. Run replit_setup_ssh once to generate one if you do not already have one.

One-click install

After clicking the button, your host will prompt you to fill: REPLIT_SSH_REQUEST_TIMEOUT_MS.

Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Replit SSH)

{
  "mcpServers": {
    "Replit SSH": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-replit-ssh"
      ],
      "env": {
        "REPLIT_SSH_REQUEST_TIMEOUT_MS": "60000"
      }
    }
  }
}

Quick Start

Install & build

cd <path-to-repo>/connectors/replit-ssh
npm install
npm run build

npx (once published)

npx -y @mindstone/mcp-server-replit-ssh

Local

node dist/index.js

Configuration

This server has no required environment variables. Authentication is via the local SSH key resolved through ~/.ssh/config.

Optional environment variables

• REPLIT_SSH_REQUEST_TIMEOUT_MS — per-request timeout in milliseconds (default: 60000, max 600000). Tool-level timeout for SFTP operations; the lower-level TCP/SSH handshake uses a separate 30-second budget.
• MCP_REPLIT_SSH_STRICT_HOST_KEY — set to 1 to require pre-populated known-hosts entries. When unset (default), unknown hosts are recorded on first contact (matches OpenSSH's StrictHostKeyChecking=accept-new); a fingerprint mismatch on a subsequent connect always fails closed regardless of this flag. See the SSH host-key verification entry in Security notes below.
• MCP_REPLIT_SSH_KNOWN_HOSTS_PATH — explicit path to the connector's SSH known-hosts file. Defaults to $MCP_WORKSPACE_PATH/.replit-ssh-known-hosts, falling back to $HOME/.replit-mcp/known_hosts. The file is created with mode 0o600 and the parent directory with mode 0o700.
• MCP_REPLIT_SSH_ALLOW_DELETE — set to 1 to enable replit_delete_file. Deletion is irreversible on Replit (no trash), so the tool fails closed with DELETE_DISABLED unless this opt-in is set.

Host configuration examples

Claude Desktop / Cursor

{
  "mcpServers": {
    "ReplitSSH": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-replit-ssh"]
    }
  }
}

Local development (no npm publish needed)

{
  "mcpServers": {
    "ReplitSSH": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/replit-ssh/dist/index.js"]
    }
  }
}

After the host launches the server, run replit_setup_ssh once to generate the local key, then add the printed public key to replit.com/account#ssh-keys.

Tools (9)

Read

• replit_check_connection — verify SSH connectivity, working directory, and SFTP support. Set verbose=true for handshake/auth diagnostics.
• replit_list_files — list files and directories at a path (relative to the project root). Default path is .. Entry types are file/directory/symlink (symlinks are reported as links, not followed — consistent with replit_stat).
• replit_read_file — read a file (capped at 1 MiB; larger files fail with FILE_TOO_LARGE rather than being truncated silently). UTF-8 text by default; binary files (detected via null-byte scan) are returned as base64.
• replit_search_files — recursive search by file-name substring and/or text-content substring (case-insensitive), with result caps (max_results, default 50) and a depth cap (max_depth, default 4). Content search skips binary files and files over 1 MB. Returns matching paths and, for content matches, up to 5 matching lines per file with line numbers (lineMatchesTruncated: true when a file has more).
• replit_stat — file/directory metadata (type, size, permissions, mtime/atime) without reading contents. Symlinks are reported as type symlink (via lstat), not followed.

Write

• replit_write_file — atomic write via temp + ext_openssh_rename with SHA-256 read-back verification. Fails closed if the server doesn't support atomic overwrite and the target already exists (we never unlink + rename, which opens a data-loss window).
• replit_move — move or rename a file or directory. Never overwrites: fails with DESTINATION_EXISTS if the destination path is taken. The destination parent directory must already exist.
• replit_delete_file — permanently delete a file (files only, not directories). Deletion is irreversible on Replit — there is no trash — so this tool is disabled unless MCP_REPLIT_SSH_ALLOW_DELETE=1 is set in the server environment (it also carries destructiveHint: true).
• replit_setup_ssh — generate an Ed25519 key pair at ~/.ssh/rebel-replit, write public/private files with mode 0600 (or icacls ACL on Windows), and append a *.replit.dev block to ~/.ssh/config. Idempotent by default; pass force_regenerate=true to replace the existing key (you will need to re-register the new public key with Replit).

Security notes

• Host allowlist. Only *.replit.dev hosts are accepted, case-insensitive suffix match. Any other host is rejected before the SSH connection is opened.
• ~/.ssh/ mutation surface. replit_setup_ssh writes to the operator's home directory (~/.ssh/rebel-replit, ~/.ssh/rebel-replit.pub, ~/.ssh/config). Configuration rewrites use a safe AST-only evaluator that skips Match exec blocks entirely, rather than the upstream ssh-config.compute() which would spawnSync them through the shell.
• Path traversal. SFTP file paths are POSIX-normalized after rejecting absolute paths and any .. segments — relative paths only, no escape from the project root.
• Atomic write invariant. replit_write_file writes to a randomized temp filename, renames via OpenSSH's POSIX rename extension (ext_openssh_rename), and verifies the final file's SHA-256 against the expected hash. If the server lacks the extension and the target file already exists, the write fails rather than falling back to unlink + rename.
• Read-back verification. Every replit_write_file re-reads the final file and asserts SHA-256 equality before returning verified: true.
• SSH host-key verification. Every outbound SSH connection passes an explicit hostVerifier to ssh2 that pins server fingerprints in a per-user known-hosts file (mode 0o600). The default behaviour mirrors OpenSSH's StrictHostKeyChecking=accept-new: the first time the connector reaches a host, the SHA-256 fingerprint is recorded and a notice is logged to stderr; on subsequent connects, a mismatch fails closed with HOST_KEY_MISMATCH. Pins are keyed by the stable proxy suffix (first DNS label stripped, e.g. riker.replit.dev) because Replit rotates the per-project hostname on every restart — a rotated hostname presenting a different key than the recorded suffix pin fails closed. The stripping stops at three labels: a three-label host pins under its full hostname, and a bare replit.dev entry is never consulted as a pin, so no single entry can act as a universal pin for every Replit host. The known-hosts file accepts both native <host> SHA256:… lines and OpenSSH ssh-keyscan output (<host> <keytype> <base64-key>). Operators who need fail-closed first-contact set MCP_REPLIT_SSH_STRICT_HOST_KEY=1 and pre-populate the known-hosts file out-of-band (e.g. ssh-keyscan riker.replit.dev > "$MCP_WORKSPACE_PATH/.replit-ssh-known-hosts" from a trusted network). Added in 0.1.2 to close audit finding replit-ssh-001.
• Untrusted-content envelopes. Content from replit_read_file, directory-entry names from replit_list_files, matched paths/lines from replit_search_files, and the peer-authored fields from replit_check_connection (server version, working directory, and diagnostic event details such as the server banner and keyboard-interactive prompts) are wrapped in <untrusted-content source="…">…</untrusted-content> envelopes per AGENTS.md invariant #6. Hosts must keep the envelopes intact when surfacing tool output to the model. Added in 0.1.2 to close audit finding replit-ssh-006; check-connection coverage added later.
• Delete is opt-in and fail-closed. replit_delete_file performs irreversible deletion (Replit has no trash), so beyond destructiveHint: true it refuses to run unless MCP_REPLIT_SSH_ALLOW_DELETE=1 is set in the server environment, failing with DELETE_DISABLED otherwise. Directories are never deleted.
• Move never overwrites. replit_move pre-checks the destination and fails with DESTINATION_EXISTS rather than clobbering an existing file.
• Algorithm allow-list. Outbound SSH connections restrict the negotiated KEX/host-key/cipher/HMAC algorithms to curve25519-sha256 + ssh-ed25519/rsa-sha2-* + ChaCha20-Poly1305/AES-GCM + ETM HMACs. Blocks downgrade negotiation to weaker suites if the proxy is ever misconfigured.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.