home / mcp / rails mcp server

Rails MCP Server

Provides an MCP server to analyze and interact with Rails projects through a structured API for code exploration and development.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "maquina-app-rails-mcp-server": {
      "command": "rails-mcp-server",
      "args": []
    }
  }
}

You can use the Rails MCP Server to give large language models structured access to Rails projects for code analysis, exploration, and development assistance. It manages multiple projects, exposes Rails-specific insights, and works with MCP-compatible clients to streamline AI-assisted coding workflows.

How to use

Start by launching the server in the mode that fits your workflow. Use STDIO mode for direct integration with MCP clients that communicate over standard input and output. Use HTTP mode if you need JSON-RPC over HTTP and real-time updates via Server-Sent Events (SSE). When you are ready to switch projects, use the available tools to select a Rails project and begin exploring code, routes, models, and configurations.

How to install

Prerequisites: you need Ruby installed to work with the Rails MCP Server. Ensure Ruby is available in your PATH before proceeding.

Install the MCP server gem to add the rails-mcp-server executable to your system.

Install the gem:

gem install rails-mcp-server

After installation, you can run the server in STDIO mode or in HTTP mode with a chosen port.

Configuration and usage notes

Configure which Rails projects you want to expose to the MCP server by editing a configuration file stored per your environment. The server follows the XDG Base Directory Specification for its configuration. The first run creates a config directory and an empty projects.yml file.

To prepare projects, create a YAML file with each project name and its path, for example:

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

Net security note: when enabling HTTP access from other machines, use the bind-all option only on trusted networks. The server includes origin and IP validations but exposing it increases the attack surface.

Starting the server in HTTP or STDIO mode

STDIO mode (default) is used for direct CLI or client integrations that communicate via standard input/output.

HTTP mode starts an HTTP server with JSON-RPC and SSE endpoints. Use the following commands to start in each mode.

# 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

# Start in HTTP mode binding to all interfaces (for local network access)
rails-mcp-server --mode http --bind-all

Network access and security (HTTP mode)

By default, the HTTP server binds to localhost. If you need to access it from other machines on your local network, use the --bind-all flag.

Security reminder: keep HTTP exposure limited to trusted networks. The server validates origins and IP addresses, but exposing services increases risk.

Claude Desktop integration

You can integrate with Claude Desktop via an automatic setup or manual configuration. The setup script prepares the MCP server directory structure and updates Claude Desktop accordingly.

Option 1: setup script (recommended)

rails-mcp-setup-claude

Option 2: manual configuration involves creating the proper config directory and a projects.yml file, then adding an MCP server entry to Claude Desktop’s config. The example below shows how to reference the server command and arguments directly.

Ruby version manager considerations

Claude Desktop launches the MCP server using your system Ruby. If you use a Ruby version manager, ensure the server runs with the same Ruby version by pointing to the Ruby shim path in your configuration.

Using an MCP proxy (advanced)

If you need to bridge STDIO clients with HTTP/SSE capabilities, you can run an MCP proxy that connects to the HTTP endpoints. Start the server in HTTP mode, then run a proxy that forwards to the SSE endpoint.

Available tools

switch_project

Change the active Rails project to interact with a different codebase. Must be called before using other tools. Uses the projects.yml configuration.

project_info

Retrieve comprehensive information about the current Rails project, including Rails version, directory structure, API-only status, and overall organization.

list_files

List files in the Rails project matching criteria. Use optional directory and pattern arguments to explore specific areas or file types.

get_file

Retrieve the complete content of a specific file from the project for examination.

get_routes

Retrieve all HTTP routes defined in the Rails application with their controllers and actions.

analyze_models

Retrieve detailed information about Active Record models, including schema, associations, and source code for a given model.

get_schema

Retrieve database schema information for all tables or a specific table with detailed column data and constraints.

analyze_controller_views

Analyze the relationships between controllers, actions, and their corresponding views.

analyze_environment_config

Analyze environment configurations for inconsistencies, security issues, and missing variables.

load_guide

Load documentation guides from Rails, Turbo, Stimulus, Kamal, or Custom to provide context.