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.
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
The Rails MCP Server follows the XDG Base Directory Specification for configuration files:
$XDG_CONFIG_HOME/rails-mcp
or ~/.config/rails-mcp
if XDG_CONFIG_HOME is not set%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.
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:
http://localhost:<port>/mcp/messages
http://localhost:<port>/mcp/sse
Customize logging with:
# Set the log level (debug, info, error)
rails-mcp-server --log-level debug
rails-mcp-setup-claude
The script will:
projects.yml
file if it doesn't existAfter running the script, restart Claude Desktop to apply the changes.
projects.yml
file in that directory with your Rails projects~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"railsMcpServer": {
"command": "ruby",
"args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"]
}
}
}
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"]
}
}
}
For using HTTP/SSE capabilities with clients that only support STDIO:
rails-mcp-server --mode http
# Install the Node.js based MCP proxy
npm install -g mcp-remote
# Run the proxy
npx mcp-remote http://localhost:6029/mcp/sse
{
"mcpServers": {
"railsMcpServer": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:6029/mcp/sse"]
}
}
}
switch_project
Changes the active Rails project.
Parameters:
project_name
: (String, required) Name of the project as defined in the projects.yml fileExamples:
Can you switch to the "store" project so we can explore it?
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?
list_files
Lists files in the Rails project matching specific criteria.
Parameters:
directory
: (String, optional) Directory path relative to project rootpattern
: (String, optional) File pattern using glob syntaxExamples:
Show me all the controller files in the app/controllers directory.
get_file
Retrieves the complete content of a specific file.
Parameters:
path
: (String, required) File path relative to the project rootExamples:
Please show me the content of app/controllers/products_controller.rb
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?
analyze_models
Retrieves detailed information about Active Record models.
Parameters:
model_name
: (String, optional) Class name of a specific modelExamples:
I'd like to understand the User model in detail. Can you show me its schema, associations, and code?
get_schema
Retrieves database schema information.
Parameters:
table_name
: (String, optional) Database table nameExamples:
I'd like to see the structure of the users table. Can you retrieve that schema information?
analyze_controller_views
Analyzes relationships between controllers, actions, and views.
Parameters:
controller_name
: (String, optional) Name of a specific controllerExamples:
Can you analyze the Users controller and its views to help me understand the UI flow?
analyze_environment_config
Analyzes environment configurations.
Parameters: None
Examples:
Can you analyze the environment configurations to find any security issues or missing environment variables?
load_guide
Loads documentation guides.
Parameters:
guides
: (String, required) Guide library: 'rails', 'turbo', 'stimulus', 'kamal', or 'custom'guide
: (String, optional) Specific guide name to loadExamples:
Can you load the Rails getting started guide?
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.
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.
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.
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"
]
}
}
}
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.
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.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
~/.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