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.
📌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
-
Create the config directory for your platform:
- macOS:
$XDG_CONFIG_HOME/rails-mcp
or~/.config/rails-mcp
- Windows:
%APPDATA%\rails-mcp
- macOS:
-
Create a
projects.yml
file in that directory listing your Rails projects. -
Locate or create the Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Add or update MCP server configuration:
{
"mcpServers": {
"railsMcpServer": {
"command": "ruby",
"args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"]
}
}
}
- 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:
- STDIO mode (default): Communicates over standard input/output
- 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 inprojects.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:
- Start the Rails MCP Server (default STDIO mode).
- Connect your MCP-compatible client.
- 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.