百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
R

rails-mcp-server

> 编程语言
开源

这是一个 Ruby gem 实现的模型上下文协议 (MCP) 服务器,适用于 Rails 项目。此服务器允许大型语言模型 (LLM) 与 Rails 项目进行交互。

566 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

这是一个 Ruby gem 实现的模型上下文协议 (MCP) 服务器,适用于 Rails 项目。此服务器允许大型语言模型 (LLM) 与 Rails 项目进行交互。

Rails MCP Server

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.

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 with filtering options
  • Inspect model information and relationships (with Prism static analysis)
  • Get database schema information
  • Analyze controller-view relationships
  • Analyze environment configurations
  • Access comprehensive Rails, Turbo, Stimulus, and Kamal documentation
  • Context-efficient architecture with progressive tool discovery
  • Seamless integration with LLM clients

Installation

Install the gem:

bash
gem install rails-mcp-server

After installation, the following executables will be available in your PATH:

  • rails-mcp-server - The MCP server itself
  • rails-mcp-config - Interactive configuration tool (recommended)
  • rails-mcp-setup-claude - Legacy Claude Desktop setup script
  • rails-mcp-server-download-resources - Legacy resource download script

Configuration

Using the Configuration Tool (Recommended)

The easiest way to configure the Rails MCP Server is using the interactive configuration tool:

bash
rails-mcp-config

This provides a user-friendly TUI (Terminal User Interface) for:

  • Managing Projects: Add, edit, remove, and validate Rails projects
  • Downloading Guides: Download Rails, Turbo, Stimulus, and Kamal documentation
  • Importing Custom Guides: Add your own markdown documentation
  • Claude Desktop Integration: Automatically configure Claude Desktop

The tool uses Gum for an enhanced experience if installed, but works with a basic terminal fallback.

bash
# Install Gum for best experience (optional)
brew install gum        # macOS
sudo apt install gum    # Debian/Ubuntu
yay -S gum              # Arch Linux

Manual 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 manually:

  1. Edit the projects.yml file in your config directory to include your Rails projects:
yaml
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.

Usage

Starting the server

The Rails MCP Server can run in two modes:

  1. STDIO mode (default): Communicates over standard input/output for direct integration with clients like Claude Desktop.
  2. HTTP mode: Runs as an HTTP server with JSON-RPC and Server-Sent Events (SSE) endpoints.
bash
# 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

When running in HTTP mode, the server provides two endpoints:

  • JSON-RPC endpoint: http://localhost:/mcp/messages
  • SSE endpoint: http://localhost:/mcp/sse

Network Access (HTTP Mode)

By 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:

bash
# 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 8080

When using --bind-all:

  • The server binds to 0.0.0.0 instead of localhost
  • Access is allowed from local network IP ranges (192.168.x.x, 10.x.x.x)
  • The server accepts connections from .local domain names (e.g., my-computer.local)
  • Security features remain active to prevent unauthorized access

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.

Logging Options

The server logs to a file in the ./log directory by default. You can customize logging with these options:

bash
# Set the log level (debug, info, error)
rails-mcp-server --log-level debug

Claude Desktop Integration

The Rails MCP Server can be used with Claude Desktop. There are multiple options to set this up:

Option 1: Use the configuration tool (recommended)

Run the interactive configuration tool and select "Claude Desktop integration":

bash
rails-mcp-config

The tool will:

  • Detect your current Claude Desktop configuration
  • Let you choose between STDIO or HTTP mode
  • Automatically find the correct Ruby and server paths
  • Create a backup before making changes
  • Update the Claude Desktop configuration

Option 2: Use the setup script (legacy)

Run the setup script which will automatically configure Claude Desktop:

bash
rails-mcp-setup-claude

The script will:

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

After running the script, restart Claude Desktop to apply the changes.

Option 3: Direct Configuration

  1. Create the appropriate config directory for your platform:

    • macOS: $XDG_CONFIG_HOME/rails-mcp or ~/.config/rails-mcp if XDG_CONFIG_HOME is not set
    • Windows: %APPDATA%\rails-mcp
  2. Create a projects.yml file in that directory with your Rails projects.

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

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

Ruby Version Manager Users

Two different Rubies are involved, and the server handles them differently.

1. The Ruby that runs the MCP server

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:

json
{
  "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.

2. The Ruby used to introspect each Rails project

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 PATH workaround 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.

Using an MCP Proxy (Advanced)

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:

  1. Start the Rails MCP Server in HTTP mode:
bash
rails-mcp-server --mode http
  1. Install and run an MCP proxy. There are several implementations available in different languages. An MCP proxy allows a client that only supports STDIO communication to communicate via HTTP SSE. Here's an example using a JavaScript-based MCP proxy:
bash
# 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
  1. Configure Claude Desktop (or other LLM client) to use the proxy instead of connecting directly to the server:
json
{
  "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.

GitHub Copilot Agent Integration

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.

Quick Setup

  1. Configure MCP - Create .github/copilot/mcp.json in your repository:
json
{
  "mcpServers": {
    "rails": {
      "type": "local",
      "command": "rails-mcp-server",
      "args": ["--single-project"],
      "tools": ["switch_project", "search_tools", "execute_tool"]
    }
  }
}
  1. Setup Steps - Create .github/workflows/copilot-setup-steps.yml:
yaml
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-server

Alternative: Environment Variable

You can also use the RAILS_MCP_PROJECT_PATH environment variable:

json
{
  "mcpServers": {
    "rails": {
      "type": "local",
      "command": "rails-mcp-server",
      "env": {
        "RAILS_MCP_PROJECT_PATH": "."
      },
      "tools": ["switch_project", "search_tools", "execute_tool"]
    }
  }
}

Limitations

  • GitHub Copilot Agent only supports MCP tools, not resources or prompts
  • The load_guide analyzer works via execute_tool, but requires guides to be downloaded during setup

For detailed instructions, see docs/COPILOT_AGENT.md.

How the Server Works

The Rails MCP Server implements the Model Context Protocol using either:

  • STDIO mode: Reads JSON-RPC 2.0 requests from standard input and returns responses to standard output.
  • HTTP mode: Provides HTTP endpoints for JSON-RPC 2.0 requests and Server-S

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言