Rails MCP Server

A Ruby implementation of a Model Context Protocol (MCP) server for Rails projects. Let LLMs interact with your Rails codebase through code analysis, exploration, and development assistance.

Current Version: 2.0.0

What is MCP?

The Model Context Protocol (MCP) is a standardized way for AI models to interact with their environment. It defines a structured method for models to request and use tools, access resources, and maintain context during interactions.

Rails MCP Server implements the MCP specification to give AI models access to Rails projects for code analysis, exploration, and assistance.

Features

• Manage multiple Rails projects with auto-detection
• Browse project files and structures
• View Rails routes with filtering
• Inspect model information and relationships (Prism static analysis)
• Get database schema information
• Analyze controller-view relationships
• Analyze environment configurations
• Read and glob project files through dedicated tools
• Access Rails, Turbo, Stimulus, and Kamal documentation
• Context-efficient architecture with progressive tool discovery
• GitHub Copilot Agent support (v1.5.0+)
• Rails 8.1+ compatibility (v1.5.0+)

Quick Start

1. Install the Gem

gem install rails-mcp-server

2. Configure Projects

Option A: Interactive configuration

rails-mcp-config

This provides a TUI for managing projects, downloading guides, and configuring Claude Desktop.

Option B: Single-project mode (v1.5.0+)

For quick usage with the current directory:

cd /path/to/your/rails/app
rails-mcp-server --single-project

Option C: Environment variable (v1.5.0+)

export RAILS_MCP_PROJECT_PATH=/path/to/your/rails/app
rails-mcp-server

3. Configure Your AI Client

Claude Desktop

Select “Claude Desktop integration” in the configuration tool, or manually add to claude_desktop_config.json:

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "ruby",
      "args": ["/path/to/rails-mcp-server/exe/rails-mcp-server"]
    }
  }
}

GitHub Copilot Agent (v1.5.0+)

See the Copilot Agent Setup Guide for detailed instructions.

Project Detection (v1.5.0+)

The server uses priority-based project detection:

When only one project is configured, the server auto-switches to it.

Available Tools

The server provides 3 registered tools plus internal analyzers accessible via execute_tool.

Removed in v2.0.0: the execute_ruby tool has been removed. The server is now introspection-only — use the dedicated analyzers below (e.g. get_file, list_files, get_routes, get_schema). See Migrating from execute_ruby.

Registered Tools

Internal Analyzers

Usage Examples

Switch Project

switch_project(project_name: "my_rails_app")

Get Routes

execute_tool(tool_name: "get_routes")
execute_tool(tool_name: "get_routes", params: { controller: "users" })
execute_tool(tool_name: "get_routes", params: { verb: "POST" })

Analyze Models

execute_tool(tool_name: "analyze_models")
execute_tool(tool_name: "analyze_models", params: { model_name: "User" })
execute_tool(tool_name: "analyze_models", params: { model_name: "User", analysis_type: "full" })

Tips:

• Use CamelCase singular: User, BlogPost, OrderItem
• Use analysis_type: "full" to include Prism static analysis (callbacks, scopes, methods)

Get Schema

execute_tool(tool_name: "get_schema")
execute_tool(tool_name: "get_schema", params: { table_name: "users" })
execute_tool(tool_name: "get_schema", params: { detail_level: "tables" })

Tips:

• Use snake_case plural: users, blog_posts, order_items
• Use detail_level: "tables" for a quick table list

Read a File

execute_tool(tool_name: "get_file", params: { path: "Gemfile" })
execute_tool(tool_name: "get_file", params: { path: "app/models/user.rb" })

Paths are relative to the project root. Reads are confined to the project directory, and sensitive files (.env, credentials, keys) are refused.

Find Files

execute_tool(tool_name: "list_files", params: { pattern: "app/models/**/*.rb" })
execute_tool(tool_name: "list_files", params: { pattern: "app/**/*user*" })

Migrating from execute_ruby

The execute_ruby tool was removed in v2.0.0. It ran caller-supplied Ruby via bin/rails runner, which made it an arbitrary-code-execution surface a pattern-based sandbox could not safely contain. The server is an introspection tool, and its dedicated analyzers cover what execute_ruby was used for:

Ad-hoc live data queries (User.count, custom scopes) are intentionally no longer supported. If you rely on free-form execution, pin to the 1.6.x line, which retains the hardened execute_ruby.

Server Modes

STDIO Mode (Default)

For direct integration with Claude Desktop:

rails-mcp-server

Single-Project Mode (v1.5.0+)

For working with the current directory only:

cd /path/to/rails/app
rails-mcp-server --single-project

HTTP Mode

For HTTP endpoints with JSON-RPC and SSE:

rails-mcp-server --mode http
rails-mcp-server --mode http -p 8080
rails-mcp-server --mode http --bind-all  # Allow LAN access

Endpoints:

• JSON-RPC: http://localhost:6029/mcp/messages
• SSE: http://localhost:6029/mcp/sse

Configuration

Environment Variable (v1.5.0+)

Set the project path explicitly:

export RAILS_MCP_PROJECT_PATH=~/projects/my-rails-app
rails-mcp-server

Manual Project Configuration

Edit ~/.config/rails-mcp/projects.yml:

store: "~/projects/store"
blog: "~/projects/rails-blog"
ecommerce: "/full/path/to/ecommerce-app"

Ruby Version Manager Users

Claude Desktop bypasses version manager initialization. Use the Ruby shim path:

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "/home/your_user/.rbenv/shims/ruby",
      "args": ["/path/to/rails-mcp-server/exe/rails-mcp-server"]
    }
  }
}

The rails-mcp-config tool detects this automatically.

Documentation Resources

Access comprehensive documentation through load_guide:

execute_tool(tool_name: "load_guide", params: { library: "rails" })
execute_tool(tool_name: "load_guide", params: { library: "rails", guide: "getting_started" })
execute_tool(tool_name: "load_guide", params: { library: "rails", guide: "active_record_basics" })
execute_tool(tool_name: "load_guide", params: { library: "turbo" })
execute_tool(tool_name: "load_guide", params: { library: "stimulus" })
execute_tool(tool_name: "load_guide", params: { library: "kamal" })
execute_tool(tool_name: "load_guide", params: { library: "custom" })

Available libraries:

Download guides using the configuration tool:

rails-mcp-config
# Select "Download guides"

Breaking Change in v1.5.0: The guides parameter was renamed to library.

• Old: params: { guides: "rails" }
• New: params: { library: "rails" }

Analyzer Parameter Reference

Common Parameter Values

detail_level:

• names - Minimal output (just names/paths)
• summary - Compact overview
• full - Complete details (default)

analysis_type (for models and controllers):

• introspection - Uses Rails runtime APIs (default)
• static - Uses Prism AST parsing
• full - Both introspection and static analysis

Using with MCP Proxy

For STDIO-only clients that need HTTP/SSE capabilities:

# Start server in HTTP mode
rails-mcp-server --mode http

# Install and run MCP proxy
npm install -g mcp-remote
npx mcp-remote http://localhost:6029/mcp/sse

Configure Claude Desktop to use the proxy:

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:6029/mcp/sse"]
    }
  }
}

Testing and Debugging

Use MCP Inspector to test the server:

npm -g install @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector /path/to/rails-mcp-server

The Inspector UI lets you:

• See all available tools
• Execute tool calls interactively
• View request and response details
• Debug issues in real-time

Security

Introspection-only (v2.0.0+)

The server does not execute caller-supplied Ruby. It exposes a fixed set of introspection analyzers, so there is no arbitrary-code-execution surface. (The free-form execute_ruby tool was removed in v2.0.0.)

The tools that boot the app (get_schema, get_routes, and the introspection half of analyze_models / analyze_controller_views) run bin/rails runner with fixed, server-authored scripts; caller input is passed as validated parameters, never interpolated as code. Booting a project runs that project’s environment, so point the server only at Rails projects you trust.

Input Validation

All file-accessing tools use centralized input validation (PathValidator):

• Path traversal prevention - Blocks ../ and absolute paths that escape the project root
• Sensitive file protection - Filters master.key, credentials.yml.enc, .env files
• Shell injection prevention - Uses safe argument passing
• SQL injection prevention - Validates table names in schema queries

Compatibility

Changelog Highlights

v2.0.0

Breaking Changes:

• Removed the execute_ruby tool. The server is now introspection-only; use the dedicated analyzers (see Migrating from execute_ruby). Bootstrap tools reduced from 4 to 3.

Security:

• Removing execute_ruby eliminates the arbitrary-code-execution surface behind the v1.6.x hardening series.

v1.6.x

Security:

• Hardened, then removed, the execute_ruby sandbox: blocked the PTY.spawn command-execution path and other stdlib escapes, hard-blocked dynamic dispatch to execution sinks, and fixed a ReDoS in the static scan (v1.6.1). Thanks to Pluto Security for the responsible disclosure.
• Puma upgraded to 8.0.2, clearing CVE-2026-47736 / CVE-2026-47737.

Breaking Changes:

• Dropped Ruby 3.2 support (minimum is now Ruby 3.3).

v1.5.0

New Features:

• GitHub Copilot Agent support
• --single-project flag for single-project mode
• RAILS_MCP_PROJECT_PATH environment variable
• Auto-detection of Rails apps and engines
• Auto-switch when only one project configured

Security:

• Added PathValidator for centralized input sanitization
• Added CI security infrastructure (Dependabot, CodeQL, OpenSSF Scorecard)

Breaking Changes:

• load_guide parameter renamed: guides → library

Next Steps