Rails Explorer MCP server

The Rails MCP Server is a Ruby implementation that enables Large Language Models (LLMs) to interact with Rails projects through the Model Context Protocol. This server allows AI models to analyze code, explore project structures, and provide development assistance by implementing a standardized protocol for environment interaction.

Installation

Install the gem using the following command:

gem install rails-mcp-server

After installation, two executables will be available in your PATH:

• rails-mcp-server
• rails-mcp-setup-claude

Configuration

The Rails MCP Server follows the XDG Base Directory Specification for configuration files:

• On macOS: $XDG_CONFIG_HOME/rails-mcp or ~/.config/rails-mcp if XDG_CONFIG_HOME is not set
• On Windows: %APPDATA%\rails-mcp

The server automatically creates these directories and an empty projects.yml file on first run.

To configure your projects, edit the projects.yml file:

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

Each key is a project name (used with the switch_project tool), and each value is the path to the project directory.

Usage

Starting the Server

The Rails MCP Server can run in two modes:

# Start in default STDIO mode
rails-mcp-server

# Start in HTTP mode on the default port (6029)
rails-mcp-server --mode http

# Start in HTTP mode on a custom port
rails-mcp-server --mode http -p 8080

When running in HTTP mode, the server provides two endpoints:

• JSON-RPC endpoint: http://localhost:<port>/mcp/messages
• SSE endpoint: http://localhost:<port>/mcp/sse

Logging Options

Customize logging with:

# Set the log level (debug, info, error)
rails-mcp-server --log-level debug

Claude Desktop Integration

Option 1: Use the Setup Script (Recommended)

rails-mcp-setup-claude

The script will:

• Create the appropriate config directory for your platform
• Create an empty projects.yml file if it doesn't exist
• Update the Claude Desktop configuration

After running the script, restart Claude Desktop to apply the changes.

Option 2: Direct Configuration

1. Create the appropriate config directory for your platform
2. Create a projects.yml file in that directory with your Rails projects
3. Find or create the Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
4. Add or update the MCP server configuration:

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

5. Restart Claude Desktop to apply the changes.

Ruby Version Manager Users

For Ruby version manager users (e.g., rbenv, RVM), use the Ruby shim path:

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

Using an MCP Proxy (Advanced)

For using HTTP/SSE capabilities with clients that only support STDIO:

1. Start the Rails MCP Server in HTTP mode:

rails-mcp-server --mode http

2. Install and run an MCP proxy:

# Install the Node.js based MCP proxy
npm install -g mcp-remote

# Run the proxy
npx mcp-remote http://localhost:6029/mcp/sse

3. Configure Claude Desktop to use the proxy:

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

Available Tools

1. switch_project

Changes the active Rails project.

Parameters:

• project_name: (String, required) Name of the project as defined in the projects.yml file

Examples:

Can you switch to the "store" project so we can explore it?

2. project_info

Retrieves comprehensive information about the current Rails project.

Parameters: None

Examples:

Tell me about this Rails application. What version is it running and how is it organized?

3. list_files

Lists files in the Rails project matching specific criteria.

Parameters:

• directory: (String, optional) Directory path relative to project root
• pattern: (String, optional) File pattern using glob syntax

Examples:

Show me all the controller files in the app/controllers directory.

4. get_file

Retrieves the complete content of a specific file.

Parameters:

• path: (String, required) File path relative to the project root

Examples:

Please show me the content of app/controllers/products_controller.rb

5. get_routes

Retrieves all HTTP routes defined in the Rails application.

Parameters: None

Examples:

Can you show me all the routes defined in this application?

6. analyze_models

Retrieves detailed information about Active Record models.

Parameters:

• model_name: (String, optional) Class name of a specific model

Examples:

I'd like to understand the User model in detail. Can you show me its schema, associations, and code?

7. get_schema

Retrieves database schema information.

Parameters:

• table_name: (String, optional) Database table name

Examples:

I'd like to see the structure of the users table. Can you retrieve that schema information?

8. analyze_controller_views

Analyzes relationships between controllers, actions, and views.

Parameters:

• controller_name: (String, optional) Name of a specific controller

Examples:

Can you analyze the Users controller and its views to help me understand the UI flow?

9. analyze_environment_config

Analyzes environment configurations.

Parameters: None

Examples:

Can you analyze the environment configurations to find any security issues or missing environment variables?

10. load_guide

Loads documentation guides.

Parameters:

• guides: (String, required) Guide library: 'rails', 'turbo', 'stimulus', 'kamal', or 'custom'
• guide: (String, optional) Specific guide name to load

Examples:

Can you load the Rails getting started guide?

Testing and Debugging

Use the MCP Inspector for testing and debugging:

# Install and run MCP Inspector
npm -g install @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector /path/to/rails-mcp-server

This will start your Rails MCP Server in HTTP mode and launch the MCP Inspector UI in your browser, allowing you to test tools interactively.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "railsMcpServer" '{"command":"ruby","args":["/full/path/to/rails-mcp-server/exe/rails-mcp-server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect