SSH Rails Runner

You can securely execute Rails console commands on a remote environment through SSH using this MCP server. It supports read-only operations, safe dry-runs for mutations, and controlled execution of approved mutations, all wired to work with your Rails project context.

How to use

Set up the MCP server locally, then connect a client to run read-only commands or perform mutations in your deployed Rails environment.

Use the read-only workflow to inspect data or verify queries without changing the database. Use the mutate workflow only after you have reviewed the prepared code. The server provides a dry-run option so you can preview mutations before any change is applied.

Configure your MCP client with the provided server integration. You will load the MCP server by supplying a stdio-based command that starts the local runner, passing SSH connection details and Rails project context.

Example workflows you can perform include preparing code snippets, executing them in read-only mode, and executing approved mutations. The prepare step saves a Ruby snippet for review, the read-only execute runs the snippet safely, and the mutate execute applies the changes after explicit confirmation.

How to install

Prerequisites: ensure you have Node.js installed on your local machine.

Install dependencies and build the server locally.

npm install
npm run build

Configuration and usage notes

Set the following environment variables to establish the SSH connection and Rails working directory.

SSH_HOST=your.remote.host SSH_USER=your_ssh_user SSH_PRIVATE_KEY_PATH=your_SSH_PRIVATE_KEY_PATH RAILS_WORKING_DIR=/path/to/rails/app

In your client configuration, load the MCP server using the stdio route with an explicit command and arguments as shown.

Configuration example for the client

{
  "mcpServers": {
    "ssh-rails-runner": {
      "command": "npx",
      "args": ["mcp-server-ssh-rails-runner"],
      "env": {
        "SSH_HOST": "your.remote.host",
        "SSH_USER": "your_ssh_user",
        "SSH_PRIVATE_KEY_PATH": "your_SSH_PRIVATE_KEY_PATH",
        "RAILS_WORKING_DIR": "/path/to/rails/app/root",
        "PROJECT_NAME_AS_CONTEXT": "Name that shows up in tool descriptions to help the LLM describe what kind of Rails project we're working with.",
        "CODE_SNIPPET_FILE_DIRECTORY": "/path/to/store/code/snippets/locally"
      }
    }
  }
}

Security considerations

Only connect to trusted SSH endpoints from machines you control. Review every prepared mutation carefully before executing a mutate command. Mutations run in a dangerous zone and should be confirmed by you after inspecting the prepared snippet.

Notes and tips

• Code snippets are stored locally or in a designated directory if provided. If a directory is not specified, a temporary location is used.
• The dry-run capability helps you preview the impact of mutations without applying changes.
• Keep Rails project context up to date to ensure the tool descriptions remain accurate.

Available tools

mcp_ssh_rails_runner_prepare_code_snippet

Saves the provided Ruby code to a local file named code_snippet_<name>.json, marks it as readOnly or mutate, and opens the file for review. Returns the file:// URI of the created snippet.

mcp_ssh_rails_runner_execute_code_snippet_read_only

Reads the code snippet from the given file:// URI, verifies it is marked as readOnly, performs a safety check, and executes the Rails code in read-only mode. Returns the output.

mcp_ssh_rails_runner_execute_code_snippet_mutate

Dangerous: reads the code snippet marked mutate and executes it directly after user review. No dry run or safety checks are performed.