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 pr
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 pr
A Ruby 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, providing capabilities for code analysis, exploration, and development assistance.
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.
Install the gem:
gem install rails-mcp-serverAfter installation, the following executables will be available in your PATH:
rails-mcp-server - The MCP server itselfrails-mcp-config - Interactive configuration tool (recommended)rails-mcp-setup-claude - Legacy Claude Desktop setup scriptrails-mcp-server-download-resources - Legacy resource download scriptThe easiest way to configure the Rails MCP Server is using the interactive configuration tool:
rails-mcp-configThis provides a user-friendly TUI (Terminal User Interface) for:
The tool uses Gum for an enhanced experience if installed, but works with a basic terminal fallback.
# Install Gum for best experience (optional)
brew install gum # macOS
sudo apt install gum # Debian/Ubuntu
yay -S gum # Arch LinuxThe 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-mcpThe server will automatically create these directories and an empty projects.yml file the first time it runs.
To configure your projects manually:
projects.yml file in your config directory to include your Rails projects:store: "~/projects/store"
blog: "~/projects/rails-blog"
ecommerce: "/full/path/to/ecommerce-app"Each key in the YAML file is a project name (which will be 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
# Start in HTTP mode binding to all interfaces (for local network access)
rails-mcp-server --mode http --bind-allWhen running in HTTP mode, the server provides two endpoints:
http://localhost:/mcp/messageshttp://localhost:/mcp/sseBy default, the HTTP server only binds to localhost for security. If you need to access the server from other machines on your local network (e.g., for testing with multiple devices), you can use the --bind-all flag:
# Allow access from any machine on your local network
rails-mcp-server --mode http --bind-all
# With a custom port
rails-mcp-server --mode http --bind-all -p 8080When using --bind-all:
0.0.0.0 instead of localhost.local domain names (e.g., my-computer.local)Security Note: Only use --bind-all on trusted networks. The server includes built-in security features to validate origins and IP addresses, but exposing any service to your network increases the attack surface.
The server logs to a file in the ./log directory by default. You can customize logging with these options:
# Set the log level (debug, info, error)
rails-mcp-server --log-level debugThe Rails MCP Server can be used with Claude Desktop. There are multiple options to set this up:
Run the interactive configuration tool and select "Claude Desktop integration":
rails-mcp-configThe tool will:
Run the setup script which will automatically configure Claude Desktop:
rails-mcp-setup-claudeThe script will:
projects.yml file if it doesn't existAfter running the script, restart Claude Desktop to apply the changes.
Create the appropriate config directory for your platform:
$XDG_CONFIG_HOME/rails-mcp or ~/.config/rails-mcp if XDG_CONFIG_HOME is not set%APPDATA%\rails-mcpCreate a projects.yml file in that directory with your Rails projects.
Find or create the Claude Desktop configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonAdd or update the MCP server configuration:
{
"mcpServers": {
"railsMcpServer": {
"command": "ruby",
"args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"]
}
}
}Two different Rubies are involved, and the server handles them differently.
Your MCP client (e.g. Claude Desktop) launches the server using your system's default Ruby, bypassing version-manager initialization. The server must run on the Ruby where its gem is installed, or startup fails. Point the client's command at that Ruby's absolute path — for a version manager, its shim works:
{
"mcpServers": {
"railsMcpServer": {
"command": "/home/your_user/.rbenv/shims/ruby",
"args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"]
}
}
}Replace /home/your_user/.rbenv/shims/ruby with your actual Ruby path (an rbenv/mise/asdf shim, or your rvm/chruby Ruby).
Tip: The rails-mcp-config tool detects this Ruby automatically (via RbConfig.ruby) and writes the correct absolute path when configuring Claude Desktop.
Tools that boot your app — get_schema, get_routes, and the introspection half of analyze_models / analyze_controller_views — run bin/rails inside the project directory. The server selects the project's Ruby automatically and is agnostic to your version manager: it prepends the active manager's shims (mise, asdf, rbenv) to the subprocess PATH and sources rvm when present, then uses a non-login shell so macOS path_helper cannot substitute the system Ruby. The version is taken from the project's .ruby-version / .tool-versions / .mise.toml, so different projects can use different Rubies with no extra configuration.
No manual
PATHworkaround is needed. Previously these tools could fall back to the system Ruby on mise/asdf machines, where the app's Bundler then failed to boot.
Claude Desktop and many other LLM clients only support STDIO mode communication, but you might want to use the HTTP/SSE capabilities of the server. An MCP proxy can bridge this gap:
rails-mcp-server --mode http# Install the Node.js based MCP proxy
npm install -g mcp-remote
# Run the proxy, pointing to your running Rails MCP Server
npx mcp-remote http://localhost:6029/mcp/sse{
"mcpServers": {
"railsMcpServer": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:6029/mcp/sse"]
}
}
}This setup allows STDIO-only clients to communicate with the Rails MCP Server through the proxy, benefiting from the HTTP/SSE capabilities while maintaining client compatibility.
Tip: The rails-mcp-config tool can configure HTTP mode with mcp-remote automatically.
Rails MCP Server works with GitHub Copilot coding agent out of the box. The server auto-detects Rails projects when started from a Rails directory or when configured with environment variables.
.github/copilot/mcp.json in your repository:{
"mcpServers": {
"rails": {
"type": "local",
"command": "rails-mcp-server",
"args": ["--single-project"],
"tools": ["switch_project", "search_tools", "execute_tool"]
}
}
}.github/workflows/copilot-setup-steps.yml:name: "Copilot Setup Steps"
on: workflow_dispatch
jobs:
copilot-setup-steps:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '3.3'
bundler-cache: true
- name: Install Rails MCP Server
run: gem install rails-mcp-serverYou can also use the RAILS_MCP_PROJECT_PATH environment variable:
{
"mcpServers": {
"rails": {
"type": "local",
"command": "rails-mcp-server",
"env": {
"RAILS_MCP_PROJECT_PATH": "."
},
"tools": ["switch_project", "search_tools", "execute_tool"]
}
}
}load_guide analyzer works via execute_tool, but requires guides to be downloaded during setupFor detailed instructions, see docs/COPILOT_AGENT.md.
The Rails MCP Server implements the Model Context Protocol using either:
No open issues yet, or sync has not completed.