Ruby Console MCP

🚀 Ruby Console MCP Server

This is a Model Context Protocol (MCP) server that enables AI assistants to access Ruby console functionality. It allows you to execute Rails console, IRB, or Racksh commands, query models, and interact with your Ruby/Rails application via natural language, with support for persistent sessions.

✨ Features

• 🚀 Execute Rails console, IRB, or Racksh commands through MCP.
• 💾 Persistent session: Variables and state are preserved between commands.
• ⚙️ Configurable console command (supports Rails, IRB, Racksh, or any Ruby REPL).
• 🔌 Easy integration with MCP-compatible AI assistants (Claude, Cursor, etc.).
• 📝 Clear error messages and helpful diagnostics.
• 🎯 Uses PTY for proper TTY support (works with Rails 8+, IRB, Racksh).

📦 Installation

Option 1: Install via npm (Recommended)

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

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

Option 2: Install from source

# Clone or navigate to the project directory
git clone https://github.com/tuhalang/ruby-console-mcp.git
cd ruby-console-mcp

# Install dependencies
npm install

# Build the project
npm run build

📚 Configuration

Create a configuration file or set environment variables:

Environment Variables

Example Configuration

Local Rails app:

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

Docker (no RUBY_APP_PATH needed):

export RUBY_CONSOLE_COMMAND="docker-compose exec -T web bundle exec rails c"

Running from Rails directory (no RUBY_APP_PATH needed):

# Just use default command, it will use current directory
export RUBY_CONSOLE_COMMAND="bundle exec rails c"

Custom Console Commands

You can customize the command used to start the console. Examples for Rails, IRB, and Racksh:

# Production environment
RUBY_CONSOLE_COMMAND="bundle exec rails c production"

# Sandbox mode (changes are rolled back)
RUBY_CONSOLE_COMMAND="bundle exec rails c --sandbox"

# Using Docker (no RUBY_APP_PATH needed)
RUBY_CONSOLE_COMMAND="docker-compose exec -T web bundle exec rails c"

# Using Kubernetes (no RUBY_APP_PATH needed)
RUBY_CONSOLE_COMMAND="kubectl exec -it rails-pod -- bundle exec rails c"

# Using specific Ruby version
RUBY_CONSOLE_COMMAND="rbenv exec bundle exec rails c"

# Remote server via SSH (no RUBY_APP_PATH needed)
RUBY_CONSOLE_COMMAND="ssh user@server 'cd /app && bundle exec rails c'"

# IRB (standalone Ruby)
RUBY_CONSOLE_COMMAND="irb"

# Racksh (Rack console)
RUBY_CONSOLE_COMMAND="bundle exec racksh"

⚠️ Important Note

When using Docker, Kubernetes, or remote commands, you typically don't need to set RUBY_APP_PATH since the command itself handles the context.

💻 Usage Examples

Usage with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration file:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Using npm package (Recommended):

{
  "mcpServers": {
    "ruby-console": {
      "command": "npx",
      "args": ["-y", "ruby-console-mcp"],
      "env": {
        "RUBY_APP_PATH": "/path/to/your/rails/app"
      }
    }
  }
}

Or using globally installed package:

{
  "mcpServers": {
    "ruby-console": {
      "command": "ruby-console-mcp",
      "env": {
        "RUBY_APP_PATH": "/path/to/your/rails/app"
      }
    }
  }
}

Local Rails app (from source):

{
  "mcpServers": {
    "ruby-console": {
      "command": "node",
      "args": ["/path/to/ruby-console-mcp/build/index.js"],
      "env": {
        "RUBY_APP_PATH": "/path/to/your/rails/app"
      }
    }
  }
}

Docker (no RUBY_APP_PATH needed):

{
  "mcpServers": {
    "ruby-console": {
      "command": "npx",
      "args": ["-y", "ruby-console-mcp"],
      "env": {
        "RUBY_CONSOLE_COMMAND": "docker-compose exec -T web bundle exec rails c"
      }
    }
  }
}

Other MCP Clients

Using npm package:

npx -y ruby-console-mcp

Or if installed globally:

ruby-console-mcp

From source:

node /path/to/ruby-console-mcp/build/index.js

🔧 Technical Details

How It Works

Command Execution

The server spawns a persistent console process (Rails console, IRB, or Racksh) using a pseudo-terminal (PTY) and communicates with it via stdin/stdout. Commands are sent to the console, and responses are captured and returned to the AI assistant.

Persistent Session

The console runs in a persistent session, which means:

• Variables persist: Variables defined in one command are available in subsequent commands.
• State is maintained: ActiveRecord connections, loaded classes, and other state persist.
• Efficient: No need to reload the Rails environment for each command.

Example Interactions

Simple query:

Command: User.count
Result: 42

Using variables across commands:

Command: a = User.first
Result: => #<User id: 1...>

Command: a.email
Result: => "user@example.com"

Complex operations:

Command: users = User.where('created_at > ?', 1.week.ago)
Result: => #<ActiveRecord::Relation...>

Command: users.count
Result: => 15

Available Tools

execute_ruby_command

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

Parameters:

• command (string, required): The console command to execute

Examples:

// Query a model
{
  "command": "User.count"
}

// Complex query
{
  "command": "User.where('created_at > ?', 1.week.ago).group(:role).count"
}

// Using variables (persists across commands)
{
  "command": "user = User.first"
}

// Accessing previous variable
{
  "command": "user.email"
}

execute_ruby_script

Execute a multi-line Ruby script in the console. Useful for complex operations, method definitions, or blocks of code.

Parameters:

• script (string, required): Multi-line Ruby script to execute

Examples:

// Multi-line script
{
  "script": "user = User.first\nputs user.email\nuser.update(name: 'New Name')"
}

// Method definition
{
  "script": "def greet(name)\n  puts \"Hello, #{name}!\"\nend\ngreet('World')"
}

check_ruby_console_health

Check if the console is healthy and responsive. Executes a simple test command and measures response time.

Returns:

• HEALTHY: Console responds quickly (< 5s)
• DEGRADED: Console responds but slowly (5 - 10s)
• UNHEALTHY: Console fails or very slow (> 10s)

Examples:

// Check health
{}

connect_ruby_console

Connect to the Ruby console. Starts the console if it is not already running. Returns the connection status and console information.

Parameters:

• None

Examples:

// Connect to console
{}

disconnect_ruby_console

Disconnect from the Ruby console. Stops the console process and releases resources. All variables and state will be lost after disconnecting.

Parameters:

• None

Examples:

// Disconnect from console
{}

Features & Safety

1. Persistent Session: Variables and state persist between commands for efficient workflow.
2. Multi-line Script Support: Execute complex Ruby scripts with multiple lines.
3. Health Monitoring: Check console health and responsiveness.
4. Connection Management: Connect and disconnect from console manually.
5. Timeout Protection: Commands timeout after 30 seconds (configurable via COMMAND_TIMEOUT) with progress feedback.
6. Error Parsing: Beautifully formatted error messages with stack traces.
7. Error Handling: Clear error messages for common issues.
8. Process Management: Automatic cleanup on server shutdown.
9. PTY Support: Uses pseudo-terminal for proper Rails console output (compatible with Rails 8+).

🛠️ Troubleshooting

Console Won't Start

Problem: "Failed to start console"

Solutions:

• Verify RUBY_APP_PATH points to a valid Rails application.
• Run bundle install in your Rails application directory.
• Check that RUBY_CONSOLE_COMMAND is correct for your setup.
• Ensure all dependencies are installed.

Commands Timeout

Problem: Commands return timeout message

Solutions:

• Increase COMMAND_TIMEOUT for long-running queries.
• Check if the Rails console is hanging (test manually).
• Optimize the query or command.

Output Not Captured

Problem: Command executes but returns "(No output)"

Solutions:

• Some operations may not return output (this is normal).
• Try adding .inspect or pp to the command for better output.
• Check for errors in the Rails application logs.

Connection Lost

Problem: Rails console disconnects unexpectedly

Solutions:

• Check Rails application logs for errors.
• Verify database connection is stable.
• Restart the MCP server.

🛠️ Development

# Clone the repository
git clone https://github.com/tuhalang/ruby-console-mcp.git
cd ruby-console-mcp

# Install dependencies
npm install

# Watch mode for development
npm run dev

# Build
npm run build

# Start the server
npm start

📐 Architecture

┌─────────────────┐
│   MCP Client    │
│  (Claude, etc)  │
└────────┬────────┘
         │ stdio
         │
┌────────▼────────┐
│   MCP Server    │
│   (index.ts)    │
└────────┬────────┘
         │
┌────────▼────────┐
│ Ruby Console    │
│    Manager      │
│ (ruby-console)  │
└────────┬────────┘
         │ PTY (pseudo-terminal)
┌────────▼────────┐
│ Ruby Console    │
│  (rails c/irb)  │
└─────────────────┘

🔒 Security Considerations

• This tool provides powerful access to your Rails application.
• All commands are executed immediately without confirmation.
• Consider running in sandbox mode for testing: RUBY_CONSOLE_COMMAND="bundle exec rails c --sandbox".
• Be cautious in production environments.
• Review commands carefully before execution.
• Consider implementing additional access controls based on your needs.

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.