Rails Active MCP

★ 16

from GoodPie

A Ruby gem providing secure Rails console access through MCP for AI agents and development tools.

🔥🔥🔥✓ VerifiedFreeQuick setup

Note: This is just a personal project and while it works for the most part, I am still developing it and actively trying to make it a bit more useful for my uses.

Rails Active MCP

A Ruby gem that provides secure Rails console access through Model Context Protocol (MCP) for AI agents and development tools. Built using the official MCP Ruby SDK for professional protocol handling and future-proof compatibility.

Works with any MCP-compatible client, including Claude Desktop, Claude Code, VS Code (GitHub Copilot), Cursor, Windsurf, ChatGPT, Gemini CLI, Amazon Q Developer, JetBrains IDEs, Zed, Warp, Cline, and many more.

Features

🔒 Safe Execution: Advanced safety checks prevent dangerous operations
🚀 Official MCP SDK: Built with the official MCP Ruby SDK for robust protocol handling
📊 Read-Only Queries: Safe database querying with automatic result limiting
🔍 Code Analysis: Dry-run capabilities to analyze code before execution
📝 Audit Logging: Complete execution logging for security and debugging
⚙️ Configurable: Flexible configuration for different environments
🛡️ Production Ready: Strict safety modes for production environments
⚡ Professional Implementation: Built-in instrumentation, timing, and error handling

Available MCP Tools

The Rails Active MCP server provides four powerful tools that appear automatically in any connected MCP client:

1. `console_execute`

Execute Ruby code with safety checks and timeout protection:

Purpose: Run Rails console commands safely
Safety: Built-in dangerous operation detection
Timeout: Configurable execution timeout
Logging: All executions are logged for audit

Example prompt:

"Execute User.where(active: true).count"

2. `model_info`

Get detailed information about Rails models:

Schema Information: Column types, constraints, indexes
Associations: Has_many, belongs_to, has_one relationships
Validations: All model validations and rules
Methods: Available instance and class methods

Example prompt:

"Show me the User model structure"

3. `safe_query`

Execute safe, read-only database queries:

Read-Only: Only SELECT operations allowed
Safe Execution: Automatic query analysis
Result Limiting: Prevents large data dumps
Model Context: Works within your model definitions

Example prompt:

"Get the 10 most recent orders" "Count active users"

You can pass an optional where hash to filter records before invoking the method. For example, safe_query(model: "User", method: "count", where: { active: true }) runs User.where(active: true).count. The same applies to sum, average, minimum, maximum, pluck, and exists?.

4. `dry_run`

Analyze Ruby code for safety without executing:

Risk Assessment: Categorizes code by danger level
Safety Analysis: Identifies potential issues
Recommendations: Suggests safer alternatives
Zero Execution: Never runs the actual code

Example prompt:

"Analyze this code for safety: User.delete_all"

Safety Features

Automatic Detection of Dangerous Operations

The gem automatically detects and blocks:

Mass deletions (delete_all, destroy_all)
System commands (system, exec, backticks)
File operations (File.delete, FileUtils)
Raw SQL execution
Code evaluation (eval, send)
Process manipulation (exit, fork)

Safety Levels

Critical: Never allowed (system commands, file deletion)
High: Blocked in safe mode (mass deletions, eval)
Medium: Logged but allowed (raw SQL, update_all)
Low: Generally safe (environment access, require)

Read-Only Mode

The gem can detect read-only operations and provide additional safety:

# These are considered safe read-only operations
User.find(1)
User.where(active: true).count
Post.includes(:comments).limit(10)

Architecture

Built on Official MCP Ruby SDK

Rails Active MCP uses the official MCP Ruby SDK (mcp gem) for:

Professional Protocol Handling: Robust JSON-RPC 2.0 implementation
Built-in Instrumentation: Automatic timing and error reporting
Future-Proof: Automatic updates as MCP specification evolves
Standards Compliance: Full MCP protocol compatibility

Server Implementation

The server is implemented in lib/rails_active_mcp/sdk/server.rb and provides:

STDIO Transport: Compatible with all major MCP clients
Tool Registration: Automatic discovery of available tools
Error Handling: Comprehensive error reporting and recovery
Rails Integration: Deep integration with Rails applications

Tool Architecture

Each tool is implemented as a separate class in lib/rails_active_mcp/sdk/tools/:

ConsoleExecuteTool: Safe code execution
ModelInfoTool: Model introspection
SafeQueryTool: Read-only database access
DryRunTool: Code safety analysis

Error Handling

The gem provides specific error types:

RailsActiveMcp::SafetyError: Code failed safety checks
RailsActiveMcp::TimeoutError: Execution timed out
RailsActiveMcp::ExecutionError: General execution failure

All errors are properly reported through the MCP protocol with detailed messages.

Development and Testing

# Run tests
bundle exec rspec

# Test MCP server protocol compliance
./bin/test-mcp-output

Quick Start

Get up and running in three steps:

1. Install the gem

Add to your Rails application's Gemfile:

gem 'rails-active-mcp'

bundle install

2. Run the installer

rails generate rails_active_mcp:install

This creates an initializer, server scripts, and prompts you to select which MCP clients you use. It will automatically generate the correct project-level config files (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) so your MCP client detects the server when you open the project.

3. Connect your MCP client

If you selected your MCP client during installation, you're done — just open the project and the server will be detected automatically.

For manual configuration or additional clients, the server uses STDIO transport. Below are configuration examples for popular tools.

<details> <summary>Claude Desktop</summary>

Edit your config file:

macOS/Linux: ~/.config/claude-desktop/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

Restart Claude Desktop and the tools will appear automatically.

</details> <details> <summary>Claude Code</summary>

From your Rails project directory:

claude mcp add rails-active-mcp -- bundle exec rails-active-mcp-server

Or add it to your project's .mcp.json:

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"]
    }
  }
}

</details> <details> <summary>VS Code (GitHub Copilot)</summary>

Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Tools are available in Copilot's Agent mode.

</details> <details> <summary>Cursor</summary>

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

</details> <details> <summary>Windsurf</summary>

Add to your global Windsurf config at ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

</details> <details> <summary>Zed</summary>

Add to your Zed settings (settings.json):

{
  "context_servers": {
    "rails-active-mcp": {
      "command": {
        "path": "bundle",
        "args": ["exec", "rails-active-mcp-server"],
        "env": {}
      }
    }
  }
}

</details> <details> <summary>ChatGPT Desktop</summary>

In ChatGPT Desktop, go to Settings > Connectors > Advanced > Developer Mode, then add:

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

</details> <details> <summary>Other MCP Clients</summary>

Any MCP client that supports STDIO transport can connect to this server. The key details:

Command: bundle exec rails-active-mcp-server
Working directory: Your Rails project root
Transport: STDIO (stdin/stdout)

See the full list of MCP clients for more options.

</details>

Once connected, four tools will appear automatically: console_execute, model_info, safe_query, and dry_run.

Try asking your AI assistant:

"Show me all users created in the last week"
"What's the average order value?"
"Check the User model schema and associations"
"Analyze this code for safety: User.delete_all"

Configuration

The installer creates a default configuration at config/initializers/rails_active_mcp.rb. The defaults work out of the box, but you can customize behavior:

RailsActiveMcp.configure do |config|
  # Safety and execution
  config.safe_mode = true              # Block dangerous operations
  config.command_timeout = 30          # Seconds before timeout
  config.max_results = 100             # Limit query results
  config.allowed_models = []           # Empty = all models allowed
  config.custom_safety_patterns = []   # Additional patterns to block

  # Logging
  config.enable_logging = true
  config.log_level = :info             # :debug, :info, :warn, :error
  config.log_executions = false        # Log all code executions
  config.audit_file = nil              # Path to audit log file

  # Environment presets (call instead of setting individually)
  # config.production_mode!
  # config.development_mode!
  # config.test_mode!
end

Usage

MCP Client (Recommended)

Once connected (see Quick Start), your MCP client automatically runs the server for you. The server loads your Rails application, initializes models, and provides secure access to your Rails environment via STDIO transport.

Direct Usage

You can also use the gem directly in Ruby:

# Execute code safely
result = RailsActiveMcp.execute("User.count")

# Check if code is safe
RailsActiveMcp.safe?("User.delete_all") # => false

Running the Server Manually

If you need to run the server directly (e.g., for debugging):

bundle exec rails-active-mcp-server

# With debug logging
RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server

Rake Tasks

The gem provides several rake tasks for diagnostics and testing:

# Show status and diagnostics
rails rails_active_mcp:status

# Validate configuration
rails rails_active_mcp:validate_config

# Test MCP tools are working
rails rails_active_mcp:test_tools

# Check if code is safe
rails rails_active_mcp:check_safety['User.delete_all']

# Execute code with safety checks
rails rails_active_mcp:execute['User.count']

# Print Claude Desktop configuration
rails rails_active_mcp:install_claude_config

# Run performance benchmarks
rails rails_active_mcp:benchmark

Rails Active MCP

Features

Available MCP Tools

1. console_execute

2. model_info

3. safe_query

4. dry_run

Safety Features

Automatic Detection of Dangerous Operations

Safety Levels

Read-Only Mode

Architecture

Built on Official MCP Ruby SDK

Server Implementation

Tool Architecture

Error Handling

Development and Testing

Quick Start

1. Install the gem

2. Run the installer

3. Connect your MCP client

Configuration

Usage

MCP Client (Recommended)

Direct Usage

Running the Server Manually

Rake Tasks

License

1. `console_execute`

2. `model_info`

3. `safe_query`

4. `dry_run`