@mindstone/mcp-server-replit-ssh

@mindstone/mcp-server-replit-ssh

Replit SSH MCP server — read, write, list, and check 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.1.2 · 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: 5 (connection, files, ssh-setup)
• Surface: local-protocol
• Hosts tested: Mindstone Rebel
• 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.

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 (5)

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 ..
• replit_read_file — read a file. UTF-8 text by default; binary files (detected via null-byte scan) are returned as base64.

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_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. 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 and directory-entry names from replit_list_files 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.
• 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.