Ruby Console

You run a Ruby console MCP Server to interact with your Rails or Ruby environment from MCP-enabled assistants. It lets you execute Rails console, IRB, or Racksh commands in a persistent session, query models, and manage your app through natural language.

How to use

You start the MCP server using an MCP client, such as Claude Desktop, and connect it to the Ruby console MCP. Once connected, you send single-line commands to run in the persistent console session, or send multi-line scripts for more complex operations. The console preserves variables and state across commands, so you can build workflows that span multiple commands without reloading the environment.

How to install

Prerequisites: Node.js and npm (or npx) must be available on your machine.

Option A – Install via npm (recommended) and run with npx.

# Install globally
npm install -g ruby-console-mcp

# Or use with npx (no installation needed)
npx ruby-console-mcp

Configuration

Configure how the console starts and where your application lives using environment variables.

Environment variables

RUBY_APP_PATH: Path to your Rails/Rack application (defaults to the current directory). Optional if you’re using Docker/remote commands or IRB.

RUBY_CONSOLE_COMMAND: Command to start the console (default: bundle exec rails c). Can be Rails console, IRB, Racksh, or any Ruby REPL.

COMMAND_TIMEOUT: Timeout for command execution in milliseconds (default: 30000)

Example configuration

export RUBY_APP_PATH=/path/to/your/rails/app
export RUBY_CONSOLE_COMMAND="bundle exec rails c"

Connecting to the MCP server using a client

Connect your MCP client to the Ruby console MCP to begin issuing commands. You will be able to run single-line commands or multi-line scripts in a persistent session.

Health and troubleshooting

If the console fails to start, verify the RUBY_APP_PATH points to a valid Rails application, run bundle install in that directory, and ensure RUBY_CONSOLE_COMMAND is correct for your setup. If commands timeout, increase COMMAND_TIMEOUT or investigate long-running queries.

Security and safety notes

The MCP server executes commands immediately. Consider sandboxing for testing and review commands carefully before running in production.

Development

To develop or customize locally, install dependencies and build the server, then start it in development or production mode as needed.

Architecture and flow

The MCP client communicates with the server, which runs a persistent Ruby console process via a PTY. Commands and scripts are executed in that persistent session and results are returned to the client.

Usage examples

Simple query: Command: User.count → Result: 42. Persisted state allows later commands to reference variables like a = User.first; a.email.

Troubleshooting - common issues

Console won’t start: Ensure RUBY_APP_PATH is valid, dependencies are installed, and RUBY_CONSOLE_COMMAND is correct.

Output not captured: Some operations may not return output; consider using inspect or pp for readability.

Notes

The server uses a persistent session to keep variables and state between commands, enabling efficient multi-step workflows.

Available tools

execute_ruby_command

Execute a single-line command in the console (Rails console, IRB, or Racksh)

execute_ruby_script

Execute a multi-line Ruby script in the console for complex operations or method definitions

check_ruby_console_health

Check if the console is healthy and responsive by running a test command and measuring response time

connect_ruby_console

Connect to the Ruby console, starting it if necessary and returning status information

disconnect_ruby_console

Disconnect from the Ruby console and release resources, noting that state is not preserved after disconnect