MCP HubMCP Hub
maquina-app

rails-mcp-server

by: maquina-app

A Ruby gem implementation of a Model Context Protocol (MCP) server for Rails projects. This server allows LLMs (Large Language Models) to interact with Rails projects through the Model Context Protocol.

80created 20/03/2025
Visit
Ruby
Rails

📌Overview

Purpose: To provide a Ruby implementation of a Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to interact with Rails projects effectively.

Overview: The Rails MCP Server is designed to facilitate seamless communication between AI models and Rails applications by implementing the Model Context Protocol. This standardized protocol allows AI models to perform tasks such as code analysis and exploration within Rails projects.

Key Features:

  • Manage Multiple Projects: Supports interaction with multiple Rails projects, allowing users to switch between them seamlessly.

  • Project File Exploration: Users can browse, list, and inspect files within a Rails project to analyze its structure and content.

  • Access to Rails Routes and Models: Retrieve detailed information about defined routes and Active Record models, including schema, associations, and definitions.

  • Database Schema Retrieval: Fetch schema information for the entire database or specific tables, enhancing understanding of the project’s database design.

  • MCP Compliance: Adheres to the Model Context Protocol standard, ensuring compatibility with various LLM clients.

Rails MCP Server

A Ruby implementation of a Model Context Protocol (MCP) server for Rails projects. This server allows Large Language Models (LLMs) to interact with Rails projects through the Model Context Protocol.

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.

This 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
  • Browse project files and structures
  • View Rails routes
  • Inspect model information
  • Get database schema information
  • Analyze controller-view relationships
  • Analyze environment configurations
  • Follow the Model Context Protocol standard

Installation

Install the gem:

gem install rails-mcp-server

After installation, the rails-mcp-server and rails-mcp-setup-claude executables will be available in your PATH.

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 will automatically create these directories and an empty projects.yml file the first time it runs.

To configure your projects, edit the projects.yml file in your config directory to include your Rails projects:

store: "~/projects/store"
blog: "~/projects/rails-blog"

Each key in the YAML file is a project name, and each value is the path to the project directory.

Claude Desktop Integration

The Rails MCP Server can be used with Claude Desktop. Two setup options:

Option 1: Use the setup script (recommended)

Run the setup script which will automatically configure Claude Desktop and set up the appropriate directory structure:

rails-mcp-setup-claude

This will:

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

Restart Claude Desktop to apply changes.

Option 2: Manual configuration

  1. Create the config directory for your platform:

    • macOS: $XDG_CONFIG_HOME/rails-mcp or ~/.config/rails-mcp
    • Windows: %APPDATA%\rails-mcp

  2. Create a projects.yml file in that directory listing your Rails projects.

  3. Locate 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 MCP server configuration:

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

Ruby Version Manager Users

Claude Desktop launches the MCP server using your system's default Ruby environment, bypassing version manager initialization (e.g., rbenv, RVM). Ensure the MCP server uses the same Ruby version where it was installed.

To enforce the correct Ruby version, create a symbolic link to your Ruby shim, for example:

sudo ln -s /home/your_user/.rbenv/shims/ruby /usr/local/bin/ruby

Replace the path with your actual Ruby shim location.

Usage

Starting the server

The Rails MCP Server has two modes:

  1. STDIO mode (default): Communicates over standard input/output
  2. HTTP mode: Runs an HTTP server with JSON-RPC and Server-Sent Events (SSE)

Commands:

# Start in STDIO mode (default)
rails-mcp-server

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

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

HTTP endpoints:

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

Logging Options

Logs are stored in the ./log directory by default.

Set log level:

rails-mcp-server --log-level debug

How the Server Works

The Rails MCP Server implements MCP using:

  • STDIO mode: JSON-RPC 2.0 over standard input/output
  • HTTP mode: HTTP endpoints for JSON-RPC 2.0 and SSE

Requests include sequence numbers to match responses.

Available Tools

1. switch_project

Description: Switch active Rails project.

Parameters:

  • project_name (String, required): Project name as defined in projects.yml

2. get_project_info

Description: Retrieve info about the current Rails project (Rails version, directory structure, API-only status).

Parameters: None

3. list_files

Description: List files matching criteria in the project.

Parameters:

  • directory (String, optional): Relative directory path (e.g., 'app/models')
  • pattern (String, optional): Glob pattern (e.g., '.rb')

4. get_file

Description: Retrieve content of a file with syntax highlighting.

Parameters:

  • path (String, required): Relative file path (e.g., 'app/models/user.rb')

5. get_routes

Description: Retrieve all HTTP routes defined in the Rails app.

Parameters: None

6. analyze_models

Description: Retrieve details about Active Record models.

Parameters:

  • model_name (String, optional): Specific model class name (CamelCase)

7. get_schema

Description: Retrieve database schema information.

Parameters:

  • table_name (String, optional): Specific table name (snake_case, plural)

8. analyze_controller_views

Description: Analyze controllers, their actions, and corresponding views.

Parameters:

  • controller_name (String, optional): Specific controller name (e.g., 'UsersController')

9. analyze_environment_config

Description: Analyze environment configurations for issues.

Parameters: None

Integration with LLM Clients

To use with an MCP-compatible client:

  1. Start the Rails MCP Server (default STDIO mode).
  2. Connect your MCP-compatible client.
  3. Use the tools to interact with Rails projects.

Testing and Debugging

Use the MCP Inspector to test and debug:

npm -g install @modelcontextprotocol/inspector

npx @modelcontextprotocol/inspector /path/to/rails-mcp-server

This:

  • Starts Rails MCP Server in HTTP mode
  • Launches the MCP Inspector UI in a browser (default port 6274)
  • Sets up an MCP Proxy Server (default port 6277)

The UI allows:

  • Viewing available tools
  • Interactive tool calls
  • Viewing requests/responses
  • Real-time debugging

License

Released under the MIT License.

Permission is granted, free of charge, to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software under the conditions in the license.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Contributions are welcome on GitHub at https://github.com/maquina-app/rails-mcp-server.