Rails Active MCP

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

• 🔒 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

Add this line to your application's Gemfile:

gem 'rails-active-mcp'

And then execute:

bundle install

Run the installer:

rails generate rails_active_mcp:install

This will:

• Create an initializer with configuration options
• Mount the MCP server for Rails integration
• Create a mcp.ru server file for standalone usage
• Set up audit logging

The gem is configured in config/initializers/rails_active_mcp.rb:

RailsActiveMcp.configure do |config|
  # Core configuration options
  config.allowed_commands = %w[
    ls pwd cat head tail grep find wc
    rails console rails runner
    bundle exec rspec bundle exec test
    git status git log git diff
  ]
  config.command_timeout = 30
  config.enable_logging = true
  config.log_level = :info
end

The server runs in STDIO mode, perfect for Claude Desktop integration:

$ bundle exec rails-active-mcp-server

The server automatically:

• Loads your Rails application
• Initializes all models and configurations
• Provides secure access to your Rails environment
• Uses the official MCP Ruby SDK for protocol handling

Add to your Claude Desktop configuration file:

Location:

• 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"
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "rails-active-mcp-server",
      "cwd": "/path/to/your/rails/project"
    }
  }
}

Then in Claude Desktop, you can use prompts like:

• "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"

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

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

The Rails Active MCP server provides four powerful tools that appear automatically in Claude Desktop:

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 Usage in Claude:

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

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 Usage in Claude:

"Show me the User model structure"

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 Usage in Claude:

"Get the 10 most recent orders"

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 Usage in Claude:

"Analyze this code for safety: User.delete_all"

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)

• 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)

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)

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

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

• STDIO Transport: Perfect for Claude Desktop integration
• Tool Registration: Automatic discovery of available tools
• Error Handling: Comprehensive error reporting and recovery
• Rails Integration: Deep integration with Rails applications

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

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.

$ bundle exec rspec

$ ./bin/test-mcp-output

This tests the MCP server output redirection and JSON protocol compliance.

Set the debug environment variable for detailed logging:

$ RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

The gem is available as open source under the MIT License.

• BREAKING: Migrated to official MCP Ruby SDK
• BREAKING: Removed custom MCP server implementation
• BREAKING: Simplified configuration options
• NEW: Professional protocol handling with built-in instrumentation
• NEW: Automatic MCP specification compliance
• IMPROVED: 85% reduction in codebase complexity
• IMPROVED: Better error handling and reporting
• IMPROVED: Future-proof architecture

See CHANGELOG.md for detailed version history.