Remote Code

🌏 中文

MCP Remote Code is a standalone Model Context Protocol server for working with remote machines over SSH. Its main focus is agent-style remote development, not only remote server administration.

The core tools are the ones coding agents normally rely on when working in a local repository:

• remote_glob
• remote_grep
• remote_read
• remote_write
• remote_edit
• remote_patch

Many existing SSH MCP servers expose a remote shell, and sometimes file download/upload helpers. That is useful for operations work, but it forces agents to manipulate source files through ad-hoc shell pipelines. MCP Remote Code instead exposes native agent-style file tools, modeled after OpenCode's built-in glob, grep, read, write, edit, and patch tools, so editing a remote project feels much closer to editing a local one.

The remote host stays clean: it only needs an SSH daemon. The MCP server runs locally, maintains persistent SSH/SFTP connections with ssh2, and exposes remote operations as namespaced MCP tools.

💡 Motivation

The primary motivation is the same as the original OpenCode remote plugin: some important development machines are old, locked down, or specialized enough that installing an agent runtime is not realistic.

This is common on remote VMs, lab machines, EDA workstations, embedded Linux targets, and legacy servers. They may not have a modern Node.js, may not permit long-running agent processes, and may not be suitable for extra language server or indexing daemons. Agents still need stable ways to run commands, search code, inspect files, edit files, apply patches, and move artifacts.

The OpenCode plugin proved the remote-development workflow, but it is bound to the OpenCode ecosystem and deliberately masquerades the remote machine as the agent's local workspace. In that model, the runtime environment is fully remote: the agent cannot naturally see or use local directories.

The MCP server has two different goals:

• detach the SSH remote-development tools from a single client ecosystem; and
• support workflows where local and remote work need to cooperate.

For example, an analog IC engineer might keep design notes locally, query local gm/ID lookup tables, and iterate sizing scripts on the local workstation, while asking the agent to run Spectre verification and simulation iterations on a remote EDA machine. A pure "remote shell only" MCP server is too low-level for that workflow, and a fully remote-masquerading plugin cannot naturally use the local workspace. This project is designed for that middle ground.

✨ Features

• Multi-machine connection manager.
• Saved machine templates in ~/.opencode/mcp-remote-code-configs.json.
• On-demand SSH connections with remote_connect.
• Startup auto-connect from CLI flags or environment variables.
• Persistent SSH command and SFTP connection pools.
• Remote command execution, glob, grep, read, write, edit, and patch tools.
• Explicit absolute-path file transfer tools:
  • remote_pull: remote file/directory to local absolute path.
  • remote_push: local file/directory to remote absolute path.
• Large-transfer preflight warnings with second-call force confirmation.
• Streamable HTTP transport for current MCP clients.
• Legacy HTTP+SSE compatibility for older MCP clients.

📋 Requirements

• Node.js >= 20.
• A reachable SSH server on each remote machine.
• A POSIX-like remote shell for file tools.

The remote machine does not need Node.js, MCP software, an agent, rsync, or sshpass.

🚀 Install

From a checkout:

npm install
npm run build
npm install -g .

When installed globally, the command is:

mcp-remote-code

▶️ Start The Server

Default local daemon:

mcp-remote-code

Custom bind address:

mcp-remote-code --port 3000 --host 127.0.0.1

Security note: this server has no built-in authentication. Keep the default 127.0.0.1 binding unless you place it behind your own trusted network boundary. Do not expose it directly to the internet.

🔌 MCP Endpoints

Endpoint	Purpose
http://127.0.0.1:3000/sse	Compatible endpoint. Accepts Streamable HTTP POST/GET/DELETE and legacy SSE GET.
http://127.0.0.1:3000/mcp	Streamable HTTP endpoint for current MCP clients.
http://127.0.0.1:3000/message	Legacy HTTP+SSE message endpoint.
http://127.0.0.1:3000/health	Health and status JSON.

Most MCP clients can use:

{
  "mcpServers": {
    "remote-code": {
      "url": "http://127.0.0.1:3000/sse"
    }
  }
}

🖥️ Machine Configs

Saved machine templates live at:

~/.opencode/mcp-remote-code-configs.json

Add a machine from an MCP client:

remote_add_config(
  name: "dev",
  ssh: "ssh -oHostKeyAlgorithms=+ssh-rsa user@host",
  workdir: "/home/project",
  password: "optional-password"
)

Connect later:

remote_connect(machine: "dev")

Passwords in saved templates are stored in the local JSON config file. Use file-system permissions appropriate for your machine.

⚡ Startup Auto-Connect

You can connect a machine as the daemon starts. Startup connections are not saved as templates.

mcp-remote-code \
  --remote "ssh -i ~/.ssh/id_rsa user@host" \
  --workdir /home/project \
  --name dev

Environment variable form:

export REMOTE_SSH='ssh user@host'
export REMOTE_WORKDIR='/home/project'
export REMOTE_NAME='dev'
mcp-remote-code

Supported startup variables:

Variable	Meaning
REMOTE_SSH	SSH command string.
REMOTE_WORKDIR	Remote working directory.
REMOTE_NAME	Connection name, default default.
REMOTE_PASSWORD	SSH password.
REMOTE_SUDO_PASSWORD	Password used for sudo commands.

🔑 SSH Command Support

The SSH command string must start with ssh. Common OpenSSH-style options are parsed:

• -p <port> or -p<port>
• -i <identity_file> or -i<identity_file>
• -l <user> or -l<user>
• -o Key=Value

Recognized -o values include:

• Port
• User
• IdentityFile
• HostKeyAlgorithms
• StrictHostKeyChecking=no

This server does not spawn the external ssh binary. Advanced OpenSSH client features such as ProxyJump, ProxyCommand, and custom ssh_config files are not implemented by this package.

🧰 Tools

Connection and config tools:

• remote_add_config
• remote_remove_config
• remote_list_configs
• remote_connect
• remote_disconnect
• remote_list_machines

Remote operation tools:

• remote_bash
• remote_glob
• remote_grep
• remote_read
• remote_write
• remote_edit
• remote_patch
• remote_pull
• remote_push

All remote operation tools accept an optional machine parameter. If omitted and exactly one machine is connected, that machine is used.

📦 File Transfer

remote_pull and remote_push require explicit absolute paths. The MCP server does not infer the agent workspace from its own startup directory.

Pull

Download a remote file or directory to a local absolute path:

remote_pull(
  machine: "dev",
  remotePath: "/home/project/logs",
  localPath: "/home/me/project/artifacts/logs"
)

Rules:

• remotePath must be an absolute remote path.
• localPath must be an absolute local path.
• On Windows, use a fully qualified path such as C:\work\project\artifact.bin or a UNC path, not \artifact.bin.
• Directories are copied recursively and preserve their internal tree.
• Binary files are supported.
• Same-path local files are overwritten.
• Extra local files are not deleted.

Push

Upload a local file or directory to a remote absolute path:

remote_push(
  machine: "dev",
  localPath: "/home/me/project/artifacts/logs",
  remotePath: "/home/project/logs"
)

Rules:

• localPath must be an absolute local path.
• remotePath must be an absolute remote path.
• Directories are uploaded recursively and preserve their internal tree.
• Binary files are supported.
• Symlinks and special local file types are skipped.
• Same-path remote files are overwritten.
• Extra remote files are not deleted.

Large Transfer Confirmation

Pull and push both use a two-step confirmation for large transfers.

Defaults:

• Size threshold: 25 MB.
• File-count threshold: 500 files.
• Confirmation window: 10 minutes.

The first large-transfer call returns a plan with type, byte size, file count, directory count, and source/destination paths. It does not transfer data, even if force: true is already present. Repeat the same call with force: true within the confirmation window to proceed.

Environment overrides:

Direction	Size threshold	File threshold
Pull	REMOTE_PULL_WARN_BYTES	REMOTE_PULL_WARN_FILES
Push	REMOTE_PUSH_WARN_BYTES	REMOTE_PUSH_WARN_FILES

🛠️ Development

npm install
npm run lint
npm run build
npm pack --dry-run

The npm package includes build/, README.md, and README.zh-CN.md.

🗂️ Repository Layout

This MCP server is a standalone repository. It may live next to, or inside a checkout of, an OpenCode plugin during development, but its .git directory, package metadata, README files, and npm build artifacts are independent.

License

MIT