Rails MCP Server

Rails MCP サーバー

Rails プロジェクト向けの Model Context Protocol（MCP）サーバーを Ruby で実装したものです。このサーバーを使用すると、LLM（大規模言語モデル）が Model Context Protocol を通じて Rails プロジェクトとやり取りでき、コード分析、調査、開発支援の機能を利用できます。

MCP とは？

Model Context Protocol（MCP）は、AI モデルが環境とやり取りするための標準化された方法です。モデルがツールを要求して使用し、リソースにアクセスし、やり取りの中でコンテキストを維持するための構造化された手法を定義しています。

この Rails MCP サーバーは MCP 仕様を実装し、コード分析、調査、支援を目的として AI モデルが Rails プロジェクトにアクセスできるようにします。

機能

• 複数の Rails プロジェクトを管理
• プロジェクトのファイルや構成を閲覧
• フィルタリングオプションを使って Rails のルートを表示
• モデル情報とリレーションシップを調査（Prism による静的解析を使用）
• データベーススキーマ情報を取得
• コントローラーとビューの関係を分析
• 環境設定を分析
• Rails、Turbo、Stimulus、Kamal の包括的なドキュメントにアクセス
• 段階的なツールの検出による、コンテキスト効率の高いアーキテクチャ
• LLM クライアントとのシームレスな統合

インストール

Gem をインストールします：

gem install rails-mcp-server

インストール後、次の実行ファイルが PATH から使用できるようになります：

• rails-mcp-server - MCP サーバー本体
• rails-mcp-config - 対話型設定ツール（推奨）
• rails-mcp-setup-claude - 従来の Claude Desktop 設定スクリプト
• rails-mcp-server-download-resources - 従来のリソースダウンロードスクリプト

設定

設定ツールを使用する（推奨）

Rails MCP サーバーを設定する最も簡単な方法は、対話型設定ツールを使用することです：

rails-mcp-config

このツールでは、使いやすい TUI（ターミナルユーザーインターフェース）を使って、次の操作を行えます：

• プロジェクトの管理：Rails プロジェクトの追加、編集、削除、検証
• ガイドのダウンロード：Rails、Turbo、Stimulus、Kamal のドキュメントをダウンロード
• カスタムガイドのインポート：独自の Markdown ドキュメントを追加
• Claude Desktop との統合：Claude Desktop を自動的に設定

インストールされている場合、このツールは快適に利用できるように Gum を使用しますが、基本的なターミナルでの代替手段にも対応しています。

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

手動設定

Rails MCP サーバーは、設定ファイルに XDG Base Directory 仕様を使用します：

• macOS の場合：$XDG_CONFIG_HOME/rails-mcp。XDG_CONFIG_HOME が設定されていない場合は ~/.config/rails-mcp
• Windows の場合：%APPDATA%\rails-mcp

サーバーは初回起動時に、これらのディレクトリと空の projects.yml ファイルを自動的に作成します。

プロジェクトを手動で設定するには：

1. 設定ディレクトリにある projects.yml ファイルを編集し、Rails プロジェクトを追加します：

store: "~/projects/store"
blog: "~/projects/rails-blog"
ecommerce: "/full/path/to/ecommerce-app"

YAML ファイルの各キーはプロジェクト名（switch_project ツールで使用されます）で、各値はプロジェクトディレクトリへのパスです。

使用方法

サーバーの起動

Rails MCP サーバーは、次の 2 つのモードで実行できます：

1. STDIO モード（デフォルト）：Claude Desktop などのクライアントと直接統合するため、標準入力／出力を通じて通信します。
2. HTTP モード：JSON-RPC エンドポイントと Server-Sent Events（SSE）エンドポイントを備えた HTTP サーバーとして実行します。

# 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

HTTP モードで実行すると、サーバーは次の 2 つのエンドポイントを提供します：

• JSON-RPC エンドポイント：http://localhost:<port>/mcp/messages
• SSE エンドポイント：http://localhost:<port>/mcp/sse

ネットワークアクセス（HTTP モード）

セキュリティ上の理由から、HTTP サーバーはデフォルトで localhost にのみバインドされます。ローカルネットワーク上のほかのマシンからサーバーにアクセスする必要がある場合（例：複数のデバイスでのテスト）は、--bind-all フラグを使用できます。

# 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

--bind-all を使用すると：

• サーバーは localhost ではなく 0.0.0.0 にバインドされます
• ローカルネットワークの IP 範囲（192.168.x.x、10.x.x.x）からのアクセスが許可されます
• サーバーは .local ドメイン名（例：my-computer.local）からの接続を受け付けます
• 不正アクセスを防ぐセキュリティ機能は引き続き有効です

セキュリティに関する注意：--bind-all は信頼できるネットワークでのみ使用してください。サーバーにはオリジンと IP アドレスを検証するセキュリティ機能が組み込まれていますが、ネットワークにサービスを公開すると攻撃対象領域が広がります。

ログのオプション

デフォルトでは、サーバーは ./log ディレクトリ内のファイルにログを記録します。次のオプションでログをカスタマイズできます。

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

Claude Desktop との連携

Rails MCP Server は Claude Desktop と一緒に使用できます。設定方法はいくつかあります。

オプション 1：設定ツールを使用する（推奨）

対話型の設定ツールを実行し、「Claude Desktop integration」を選択します。

rails-mcp-config

このツールでは、次のことが行われます。

• 現在の Claude Desktop の設定を検出します
• STDIO モードと HTTP モードのどちらを使用するか選択できます
• 正しい Ruby とサーバーのパスを自動的に検出します
• 変更を加える前にバックアップを作成します
• Claude Desktop の設定を更新します

オプション 2：セットアップスクリプトを使用する（旧方式）

Claude Desktop を自動的に設定するセットアップスクリプトを実行します。

rails-mcp-setup-claude

スクリプトでは、次のことが行われます。

• お使いのプラットフォームに適した設定ディレクトリを作成します
• 存在しない場合は、空の projects.yml ファイルを作成します
• Claude Desktop の設定を更新します

スクリプトの実行後、変更を適用するために Claude Desktop を再起動してください。

オプション 3：直接設定する

1. お使いのプラットフォームに適した設定ディレクトリを作成します。

   • macOS：XDG_CONFIG_HOME が設定されていない場合は、$XDG_CONFIG_HOME/rails-mcp または ~/.config/rails-mcp
   • Windows：%APPDATA%\rails-mcp

2. そのディレクトリに Rails プロジェクトを記述した projects.yml ファイルを作成します。

3. Claude Desktop の設定ファイルを探すか、作成します。

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

4. MCP サーバーの設定を追加または更新します。

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

5. 変更を適用するために Claude Desktop を再起動してください。

Ruby バージョンマネージャーを使用する場合

関係する Ruby は 2 種類あり、サーバーはそれぞれ異なる方法で処理します。

1. MCP サーバーを実行する Ruby

MCP クライアント（例：Claude Desktop）は、バージョンマネージャーの初期化を経由せず、システムのデフォルトの Ruby を使用してサーバーを起動します。サーバーは gem がインストールされている Ruby で実行する必要があり、そうでない場合は起動に失敗します。クライアントの command には、その Ruby の絶対パスを指定してください。バージョンマネージャーを使用している場合は、その shim を使用できます。

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "/home/your_user/.rbenv/shims/ruby",
      "args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"] 
    }
  }
}

/home/your_user/.rbenv/shims/ruby を実際の Ruby のパス（rbenv/mise/asdf の shim、または rvm/chruby の Ruby）に置き換えてください。

ヒント：rails-mcp-config ツールは、この Ruby を自動的に検出し（RbConfig.ruby を使用）、Claude Desktop の設定時に正しい絶対パスを書き込みます。

2. 各 Rails プロジェクトのイントロスペクションに使用する Ruby

アプリを起動するツール（get_schema、get_routes、および analyze_models / analyze_controller_views のイントロスペクション部分）は、プロジェクトディレクトリ内で bin/rails を実行します。サーバーはプロジェクトの Ruby を自動的に選択し、バージョンマネージャーの種類を問いません。アクティブなバージョンマネージャーのシム（mise、asdf、rbenv）をサブプロセスの PATH の先頭に追加し、rvm が存在する場合はその設定を読み込んだうえで、ログインシェル以外のシェルを使用します。これにより、macOS の path_helper がシステム Ruby に置き換えることを防ぎます。バージョンはプロジェクトの .ruby-version / .tool-versions / .mise.toml から取得されるため、追加の設定なしでプロジェクトごとに異なる Ruby を使用できます。

PATH を手動で回避する必要はありません。以前は、mise/asdf を使用している環境でこれらのツールがシステム Ruby にフォールバックすることがあり、その場合、アプリの Bundler が起動に失敗していました。

MCP プロキシの使用（上級者向け）

Claude Desktop やその他多くの LLM クライアントは STDIO モードの通信のみをサポートしていますが、サーバーの HTTP/SSE 機能を利用したい場合があります。MCP プロキシを使うと、このギャップを埋められます。

1. Rails MCP Server を HTTP モードで起動します。

rails-mcp-server --mode http

2. MCP プロキシをインストールして実行します。複数の言語で実装されたものがあります。MCP プロキシを使うと、STDIO 通信のみをサポートするクライアントが HTTP SSE 経由で通信できるようになります。以下は、JavaScript ベースの MCP プロキシを使用する例です。

# 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

3. サーバーに直接接続する代わりにプロキシを使用するよう、Claude Desktop（またはその他の LLM クライアント）を設定します。

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:6029/mcp/sse"]
    }
  }
}

この設定により、STDIO のみをサポートするクライアントはプロキシ経由で Rails MCP Server と通信でき、クライアントとの互換性を保ちながら HTTP/SSE 機能を利用できます。

ヒント：rails-mcp-config ツールを使うと、mcp-remote を使用した HTTP モードの設定を自動化できます。

GitHub Copilot Agent との統合

Rails MCP Server は、GitHub Copilot coding agent とそのまま連携します。Rails ディレクトリから起動した場合、または環境変数で設定した場合、サーバーは Rails プロジェクトを自動検出します。

クイックセットアップ

1. MCP を設定する — リポジトリに .github/copilot/mcp.json を作成します。

{
  "mcpServers": {
    "rails": {
      "type": "local",
      "command": "rails-mcp-server",
      "args": ["--single-project"],
      "tools": ["switch_project", "search_tools", "execute_tool"]
    }
  }
}

2. セットアップ手順 — .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-server

別の方法：環境変数

RAILS_MCP_PROJECT_PATH 環境変数を使用することもできます。

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

制限事項

• GitHub Copilot Agent がサポートするのは MCP ツールのみであり、リソースやプロンプトはサポートしていません。
• load_guide アナライザーは execute_tool 経由で動作しますが、セットアップ時にガイドをダウンロードしておく必要があります。

詳しい手順については、docs/COPILOT_AGENT.md を参照してください。

サーバーの仕組み

Rails MCP Server は、以下のいずれかを使用して Model Context Protocol を実装します。

• STDIO モード：標準入力から JSON-RPC 2.0 リクエストを読み取り、標準出力にレスポンスを返します。
• HTTP モード：JSON-RPC 2.0 リクエスト用の HTTP エンドポイントと Server-Sent Events を提供します。

MCP の仕様に従い、各リクエストにはリクエストとレスポンスを対応付けるシーケンス番号が含まれます。サーバーはプロジェクトのコンテキストを維持し、複数のコードベースにわたって Rails 固有の分析機能を提供します。

コンテキスト効率を重視したアーキテクチャ

サーバーは、コンテキストの使用量を最小限に抑えるため、段階的なツール検出アーキテクチャを採用しています。すべてのツールを最初から公開するのではなく、LLM が必要に応じてイントロスペクションアナライザーを検出し、呼び出せるようにする 3 つのブートストラップツールを提供します。

• switch_project — アクティブな Rails プロジェクトを選択します
• search_tools — カテゴリまたはキーワードで利用可能なツールを検出します
• execute_tool — パラメーターを指定して内部アナライザーを呼び出します

この設計により、初期コンテキストを小さく保ちながら、必要に応じてすべてのアナライザーを利用できます。

AI エージェントガイド

このサーバーを使用する AI エージェント（Claude、GPT など）については、以下の項目を網羅した包括的な AI エージェントガイド をご覧ください。

• クイックスタートのワークフロー
• 一般的なタスク向けのツール選択ガイド
• よくある落とし穴とその回避方法
• エラー処理とフォールバック戦略
• 他の MCP サーバー（例：Neovim MCP）との連携

利用可能なツール

このサーバーは、登録済みツール 3 つに加えて、execute_tool から利用できる内部アナライザーを提供します。

登録済みツール

1. switch_project

説明： アクティブな Rails プロジェクトを切り替えます。他のツールを使用する前に呼び出す必要があります。

パラメーター：

• project_name：（String、必須）projects.yml で定義されたプロジェクト名

切り替え後、一般的なコマンドを含むクイックスタートガイドが表示されます。

2. search_tools

説明： カテゴリーまたはキーワードから利用可能なツールを検索します。

パラメーター：

• query：（String、任意）検索語（例：'routes'、'model'、'schema'）
• category：（String、任意）カテゴリーで絞り込みます：models、database、routing、controllers、files、project、guides
• detail_level：（String、任意）出力の詳細度：'names'、'summary'、または 'full'（デフォルト：'summary'）

3. execute_tool

説明： 名前を指定して内部アナライザーを呼び出します。

パラメーター：

• tool_name：（String、必須）アナライザーの名前（例：'get_routes'、'analyze_models'）
• params：（Hash、任意）アナライザーに渡すパラメーター

内部アナライザー（execute_tool 経由）

project_info

Rails のバージョン、ディレクトリー構成、組織構造など、プロジェクトの包括的な情報を取得します。

execute_tool(tool_name: "project_info")

list_files

ディレクトリー内でパターンに一致するファイルを一覧表示します。

execute_tool(tool_name: "list_files", params: { directory: "app/models", pattern: "*.rb" })

get_file

指定したファイルの内容を取得します。

execute_tool(tool_name: "get_file", params: { path: "app/models/user.rb" })

get_routes

オプションのフィルターを指定して Rails のルートを取得します。

execute_tool(tool_name: "get_routes")
execute_tool(tool_name: "get_routes", params: { controller: "users" })
execute_tool(tool_name: "get_routes", params: { verb: "POST" })
execute_tool(tool_name: "get_routes", params: { path_contains: "api" })

analyze_models

関連付け、バリデーション、およびオプションの Prism 静的解析を用いて Active Record モデルを解析します。

execute_tool(tool_name: "analyze_models")
execute_tool(tool_name: "analyze_models", params: { model_name: "User" })
execute_tool(tool_name: "analyze_models", params: { model_name: "User", analysis_type: "full" })
execute_tool(tool_name: "analyze_models", params: { detail_level: "names" })

パラメーター：

• model_name：解析する特定のモデル
• model_names：解析するモデルの配列
• detail_level：'names'、'summary'、または 'full'
• analysis_type：'introspection'、'static'、または 'full'（Prism AST 解析を含む）

get_schema

データベースのスキーマ情報を取得します。

execute_tool(tool_name: "get_schema")
execute_tool(tool_name: "get_schema", params: { table_name: "users" })
execute_tool(tool_name: "get_schema", params: { detail_level: "tables" })

analyze_controller_views

オプションの Prism 静的解析を用いて、コントローラーとビューの関係を解析します。

execute_tool(tool_name: "analyze_controller_views")
execute_tool(tool_name: "analyze_controller_views", params: { controller_name: "users" })
execute_tool(tool_name: "analyze_controller_views", params: { controller_name: "users", analysis_type: "full" })

analyze_environment_config

環境設定の不整合やセキュリティ上の問題を解析します。

execute_tool(tool_name: "analyze_environment_config")

load_guide

Rails、Turbo、Stimulus、Kamal、またはカスタムのドキュメントガイドを読み込みます。

execute_tool(tool_name: "load_guide", params: { library: "rails" })
execute_tool(tool_name: "load_guide", params: { library: "rails", guide: "getting_started" })
execute_tool(tool_name: "load_guide", params: { library: "turbo" })
execute_tool(tool_name: "load_guide", params: { library: "stimulus" })
execute_tool(tool_name: "load_guide", params: { library: "custom", guide: "tailwind" })

リソースとドキュメント

Rails MCP Server は、load_guide ツールと MCP リソースへの直接アクセスの両方を通じて、包括的なドキュメントを利用できます。Rails、Turbo、Stimulus、Kamal の公式ガイドに加え、独自のカスタムドキュメントをインポートできます。

利用可能なリソースカテゴリー

• Rails Guides：Ruby on Rails 8.0.2 の公式ドキュメント
• Turbo Guides：Turbo（Hotwire）フレームワークの公式ドキュメント
• Stimulus Guides：Stimulus JavaScript フレームワークの公式ドキュメント
• Kamal Guides：Kamal デプロイツールの公式ドキュメント
• Custom Guides：インポートした Markdown ファイル

リソースの利用を始める

リソースを管理する最も簡単な方法は、設定ツールを使用することです。

rails-mcp-config

次に、メニューから「ガイドをダウンロード」または「カスタムガイドをインポート」を選択します。

または、従来のコマンドラインツールを使用できます。

# Download Rails guides
rails-mcp-server-download-resources rails

# Download Turbo guides
rails-mcp-server-download-resources turbo

# Import custom markdown files
rails-mcp-server-download-resources --file /path/to/your/docs/

リソースへのアクセス方法

1. ツール経由のアクセス：会話内で load_guide ツールを使用します
2. リソースへの直接アクセス：MCP クライアントは、rails://guides/{guide_name} のような URI パターンを使ってリソースを照会できます

リソースのダウンロード、管理、利用について詳しくは、リソースガイドをご覧ください。

テストとデバッグ

Rails MCP Server のテストとデバッグには、MCP サーバーのテストとデバッグ専用に設計された開発者向けツール、MCP Inspector を使うのが最も簡単です。

Rails MCP Server で MCP Inspector を使用するには、次の手順を実行します。

# Install and run MCP Inspector
npm -g install @modelcontextprotocol/inspector

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

これにより、次のことが行われます。

1. Rails MCP Server を HTTP モードで起動します
2. ブラウザーで MCP Inspector の UI を起動します（デフォルトのポート：6274）
3. MCP Proxy サーバーを設定します（デフォルトのポート：6277）

MCP Inspector の UI では、次のことができます。

• 利用可能なすべてのツールを確認する（登録済みのツールが 3 つ表示されます）
• ツール呼び出しを対話的に実行する
• リクエストとレスポンスの詳細を表示する
• リアルタイムで問題をデバッグする

Inspector の UI は、MCP サーバーと対話するための直感的なインターフェースを提供するため、Rails MCP Server の実装を簡単にテスト、デバッグできます。

テストのワークフロー

1. プロジェクトに切り替える： プロジェクト名を指定して switch_project を実行します
2. ツールを確認する： search_tools で利用可能なアナライザーを確認します
3. アナライザーをテストする： execute_tool で特定のアナライザーを呼び出します（例：get_routes、get_schema）
4. ファイルを読む： get_file を指定して execute_tool を実行します。例：{ "path": "Gemfile" }

LLM クライアントとの統合

このサーバーは、Claude Desktop などの Model Context Protocol をサポートする LLM クライアントや、その他の MCP 互換アプリケーションとの統合を目的として設計されています。

MCP クライアントで使用するには、次の手順を実行します。

1. Rails MCP Server を起動します（デフォルトでは STDIO モードを使用します）
2. MCP 互換クライアントをサーバーに接続します
3. クライアントから利用可能なツールを使って、Rails プロジェクトを操作できるようになります

ツールへのアクセス、承認、監査証跡、コストレポートを管理する AI クライアントやコントロールプレーンを利用するチームは、Governed MCP Clients をご覧ください。

セキュリティ

セキュリティ上の懸念については、SECURITY.md をご覧ください。

ライセンス

この Rails MCP サーバーは、寛容なオープンソースライセンスである MIT License のもとで公開されています。無料での使用、変更、配布、非公開での使用が認められています。

Copyright (c) 2025 Mario Alberto Chávez Cárdenas

本ソフトウェアおよび関連ドキュメントのファイル（以下「本ソフトウェア」）を取得するすべての人に対し、本ソフトウェアを制限なく取り扱うことを無償で許可します。これには、本ソフトウェアの使用、複製、変更、結合、公開、配布、サブライセンス、および販売の権利が含まれますが、これらに限定されません。また、本ソフトウェアを提供される人に同様の権利を認めることも許可されます。ただし、以下の条件に従うものとします。

上記の著作権表示および本許諾表示は、本ソフトウェアのすべての複製または実質的な部分に含めるものとします。

本ソフトウェアは「現状のまま」提供され、明示または黙示を問わず、いかなる保証もありません。これには、商品性、特定目的への適合性、および権利非侵害の保証が含まれますが、これらに限定されません。作者または著作権者は、契約、不法行為その他の行為に起因するかを問わず、本ソフトウェア、本ソフトウェアの使用、またはその他の取引に起因または関連して発生した、いかなる請求、損害その他の責任についても、一切責任を負いません。

貢献

バグ報告やプルリクエストは、GitHub の https://github.com/maquina-app/rails-mcp-server までお寄せください。