Deep Rails introspection MCP server for AI assistants

Give your AI assistant (Claude Desktop, Cursor, VS Code / Roo Code / Cline) deep, intelligent understanding of your Ruby on Rails application through the open Model Context Protocol (MCP).

Unlike basic tools that dump raw files or schema definitions, rails-mcp-insight provides cross-referenced, contextual intelligence — tracing the full request lifecycle from route → controller → model → callbacks → background jobs → mailers.

Ask your AI: "What happens when a user submits POST /orders?"

rails-mcp-insight traces the full request path statically:

{
  "route": { "method": "POST", "path": "/orders", "controller_action": "orders#create" },
  "controller": {
    "name": "OrdersController",
    "action": "create",
    "before_actions": ["authenticate_user!", "set_cart"],
    "strong_params": [{ "resource": "order", "permitted_attributes": ["product_id", "quantity", "notes"] }]
  },
  "model_operations": {
    "Order": {
      "callbacks": [
        { "type": "before_create", "target": "calculate_total" },
        { "type": "after_create", "target": "notify_warehouse" },
        { "type": "after_commit", "target": "update_inventory" }
      ],
      "validations": ["validates :quantity, presence: true"]
    }
  },
  "side_effects": {
    "jobs": ["OrderConfirmationJob"],
    "mailers": ["OrderMailer"],
    "broadcasts": false
  }
}

gem install rails-mcp-insight

Verify installation:

rails-mcp-insight --version

Add to your Rails application's Gemfile:

group :development do
  gem "rails-mcp-insight", require: false
end

Then run:

bundle install

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "rails-insight": {
      "command": "rails-mcp-insight",
      "args": ["--project", "/absolute/path/to/your/rails/app"]
    }
  }
}

Restart Claude Desktop. You will see a hammer icon 🔨 indicating that rails-mcp-insight tools are active.

Create a file at .cursor/mcp.json in your Rails root directory:

{
  "mcpServers": {
    "rails-insight": {
      "command": "rails-mcp-insight",
      "args": ["--project", "/absolute/path/to/your/rails/app"]
    }
  }
}

1. Open Cursor Settings (Ctrl+, or Cmd+,).
2. Navigate to Features → MCP Servers.
3. Click Add New MCP Server.
4. Name: rails-insight
5. Type: stdio
6. Command: rails-mcp-insight --project /absolute/path/to/your/rails/app

Add to your workspace or global .vscode/mcp.json:

{
  "servers": {
    "rails-insight": {
      "type": "stdio",
      "command": "rails-mcp-insight",
      "args": ["--project", "/absolute/path/to/your/rails/app"]
    }
  }
}

Once configured, simply chat naturally with your AI assistant. Here are concrete examples of how to use each tool:

Prompt: "Trace what happens when a user calls POST /orders"
Tool called: trace_request
Result: Traces routes → filters → strong params → model validations/callbacks → background jobs & mailers.

Prompt: "Give me a health dashboard for this Rails app."
Tool called: stats_overview
Result: Displays Ruby/Rails versions, line counts, model/controller totals, and test coverage ratios.

Prompt: "Analyze the Order model including columns, validations, and callbacks."
Tool called: analyze_model
Result: Returns schema columns with types, associations (belongs_to :user), scopes, and callback chains.

Prompt: "Show me all before_actions and strong params for OrdersController."
Tool called: analyze_controller
Result: Extracts filters, allowed params, rescue handlers, and action methods.

Prompt: "How does User relate to Product?"
Tool called: explain_association_chain
Result: Finds all association paths (e.g., User → has_many :orders → Order → belongs_to :product → Product).

Prompt: "Generate a Mermaid ERD diagram for User, Order, and Product."
Tool called: generate_erd
Result: Produces a rendered Mermaid erDiagram showing tables, attributes, and relationships.

Prompt: "Scan this project for potential SQL injection or mass assignment issues."
Tool called: check_security
Result: Static scan checking 10 security patterns (raw SQL, html_safe, params.permit, eval, system calls).

Prompt: "Where is OrderConfirmationJob defined?"
Tool called: find_definition
Result: Locates exact file and line number across the project.

If you want to contribute or test rails-mcp-insight locally:

git clone https://github.com/aditya/rails-mcp-insight.git
cd rails-mcp-insight

bundle install

bundle exec rspec

bundle exec rubocop

bundle exec bin/rails-mcp-insight --project spec/fixtures/sample_rails_app

rails-mcp-insight performs pure static analysis:

• ⚡ Fast — No Rails boot time
• 🔒 Safe — Read-only, never modifies your code or database
• 🔌 Zero config — Auto-detects Rails project structure
• 📦 Lightweight — Depends only on the official mcp gem

AI Assistant ←→ MCP (JSON-RPC / stdio) ←→ rails-mcp-insight ←→ Rails App (Filesystem)

• Read-Only: Every tool is declared with read_only_hint: true.
• Zero Execution: Does not execute Ruby code inside your Rails application.
• Local & Offline: All processing happens locally on your computer. No data is sent to external servers by this gem.

• Ruby: >= 3.0
• Rails App: Rails 5.0+, 6.x, 7.x, 8.x
• AI Host: Any MCP-compatible host (Claude Desktop, Cursor, VS Code Roo Code / Cline)

Distributed under the MIT License.

⭐ Star this repo if it helps your Rails development!