github-code-rag-mcp

一言で言うと

AIがGitHubのコードをリアルタイムに検索して流用するためのMCPサーバー。 認証を書く？検索。ミドルウェアを書く？検索。決済を書く？検索。 AIがコードを書く前に、まずGitHubで最適な実装を探します。ゼロから車輪を reinvent するのは禁止。 さらに「要件分析Agent」という方法論も内蔵しており、AIがまず調査してから着手するので、当て推量はしません。

Related MCP server: MCP Code Intelligence

課題

こんな経験はありませんか？

「ユーザー認証モジュールを書くのに、ブラウザで30分も検索して、見つけたコードの品質はまちまち。」

「GitHubには最高の実装があるのに、AIはそれを検索しようとせず、ゼロから適当に書いてしまう。」

「新しい機能を書くたびに、車輪を再発明している気分になる。答えは至る所にあるのに。」

問題はAIのコードの書き方にあります。

现在的流程：AI 想写 → 凭记忆瞎写 → 不对 → 改 → 还不对

应该有的流程：AI 想写 → 搜 GitHub → 找到最好的实现 → 复用 → 微调 → 完成

github-code-rag は GitHub を AI のツールボックスに入れます。 書きたいものがあれば、まず検索、次に流用。

コア機能

🔥 GitHubをリアルタイム検索し、最も関連性の高いコードを流用

スター数順でソートし、最も成熟したプロジェクトを優先的に選択。言語やスター数でのフィルタリングも可能。

用户：帮我写个 FastAPI 的数据库连接模块
    ↓
AI：search_github("fastapi sqlalchemy database stars:>1000")
AI：read_github_file("tiangolo/fastapi", "docs_src/sql_app/main.py")
AI：search_code("create_engine sessionmaker")
    ↓
AI：我参考了 FastAPI 官方示例，给你写好了：

# Source: tiangolo/fastapi/docs_src/sql_app/main.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
...

ブラウザを切り替えたり、リポジトリをcloneしたり、数十のタブを開いたりする必要はありません。 AIがコードを書くついでにGitHubを検索し、最適な実装を見つけて直接流用します。

📚 読み込んだコードは自動でインデックス化、使えば使うほど便利に

読み込んだリポジトリはすべてローカルのFTS5全文インデックスに保存。次回関連コードを検索する際はミリ秒単位で結果が返ってきます。

→ search_code("jwt authentication middleware")
  在 12 个已读仓库中找到 47 个匹配片段：
  - fastapi/.../auth.py:35  JWT bearer middleware
  - django/.../auth.py:128  Token authentication
  - ...

使えば使うほどローカルのコード知識ベースが大きくなり、AIのコーディング速度が向上します。

🔄 GitHub API + 公式検索ページの二重フォールバック、レート制限を気にせず

• GitHub Search API：最高品質、スター順でソート（無料枠60回/時、Token付き5000回/時）

• GitHub公式検索ページフォールバック：無料無制限、レート制限時は自動でダウングレード

• git clone不要：すべてREST API経由で、ローカルディスクを圧迫しません

🧠 おまけ：要件分析Agent — まず調査してから着手

システムプロンプトにワークフローがハードコードされており、AIが適当に書き始めることはありません。 まず類似プロジェクトを検索し、実際のプロジェクトに基づいて要件を確認してから、明確になって初めて着手します。

用户：我想做个博客系统
    ↓
AI：[搜了 10 个相关项目]
    你是要做独立博客（类似 Hugo/Hexo），还是多用户平台？
     - 独立博客（简单、SEO 好）
     - 多用户平台（功能复杂、需后台）
     - 我来根据 GitHub 项目给你推荐

「上級エンジニアの仕事の方法論をおまけで付けた」と考えてください。 不要なら使わなくても構いません。コード検索機能だけでも十分価値があります。

⚡ git clone不要 · ベクトルデータベース不要 · 依存関係はわずか1つ

• すべてGitHub REST API経由で、リポジトリのcloneは不要

• SQLite + FTS5全文インデックス、ベクトルDBやembeddingは不要

• 実行時依存は mcp>=1.0 のみ、他はすべてPython標準ライブラリ

• 起動1秒未満、メモリ50MB未満

導入前 vs 導入後

クイックスタート

1. インストール

# 推荐：pipx 一键安装（隔离环境）
pipx install github-code-rag

# 或者 uv
uv tool install github-code-rag

# 或者 pip
pip install github-code-rag

2. Token設定（推奨だが必須ではない）

export GITHUB_TOKEN=ghp_your_token_here

Tokenがなくても使用可能 — GitHub公式検索ページによるフォールバックが内蔵されており、無料無制限です。 TokenがあればGitHub APIの制限が60回/時 → 5000回/時になります。

3. AIクライアントに設定

以下の「クライアント設定」セクションを参照してください。

4. 試してみる

設定後、AIにこう話しかけてみてください：

「FastAPIのJWT認証ミドルウェアを書いて。まずGitHubで最適な実装を検索して参考にして」

AIが先にGitHubを検索し、見つけたコードに基づいて書いてくれるかどうか、確認してみてください。

クライアント設定

以下の設定はすべてstdioモードです。設定後はクライアントを再起動してください。 インストールパスが不明な場合は、which github-code-rag（macOS/Linux）または where github-code-rag（Windows）を実行してください。

Claude Code

~/.claude.json を編集し、以下を追加：

{
  "mcpServers": {
    "github-code-rag": {
      "command": "github-code-rag",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Claude Desktop

設定 → Developer → Edit Config を開き、以下を追加：

{
  "mcpServers": {
    "github-code-rag": {
      "command": "github-code-rag"
    }
  }
}

• macOSの設定ファイルパス：~/Library/Application Support/Claude/claude_desktop_config.json

• Windowsの設定ファイルパス：%APPDATA%\Claude\claude_desktop_config.json

Cursor

プロジェクト単位の設定（現在のプロジェクトのみ）：プロジェクトルートに .cursor/mcp.json を作成：

{
  "mcpServers": {
    "github-code-rag": {
      "command": "github-code-rag"
    }
  }
}

グローバル設定：設定 → MCP → Add new server → Stdio → コマンドに github-code-rag を入力

Windsurf

設定 → MCP Servers → Add MCP Server、stdioモードを選択、コマンドに以下を入力：

github-code-rag

設定ファイルの通常の場所：

• macOS：~/.codeium/windsurf/mcp_config.json

• Windows：%APPDATA%\..\Roaming\Codeium\Windsurf\mcp_config.json

Cline / Roo Code

設定 → MCP Servers → Add new MCP Server → Local executable、以下を入力：

Command: github-code-rag

または設定ファイルを直接編集：

• Cline：~/.cline/mcp.json

• Roo Code：~/.roo-code/mcp.json

Codex CLI

~/.codex/config.toml を編集し、以下を追加：

[mcp_servers.github-code-rag]
command = "github-code-rag"

OpenCode

OpenCodeの設定ファイル内の mcp servers セクションを編集：

{
  "mcpServers": {
    "github-code-rag": {
      "command": "github-code-rag"
    }
  }
}

MCPプロトコルに対応しているすべてのクライアントで使用可能です。上記リストにないクライアントを使用している場合も、基本的な設定方法は同じです — command に github-code-rag を指定してください。

ツール一覧

動作原理

┌───────────────────────────────────────────────────────────┐
│                    你的 AI 客户端                         │
│  (Claude Code / Cursor / Codex / Claude Desktop / ...)   │
└───────────────────────────┬───────────────────────────────┘
                            │ MCP protocol (stdio)
┌───────────────────────────▼───────────────────────────────┐
│                                                           │
│  ┌─────────────────────────────────────────────────┐     │
│  │  系统提示词（需求分析 Agent 方法论）             │     │
│  │    · 先搜再问 · 逐步收敛 · 复用优先              │     │
│  └───────────────────────┬─────────────────────────┘     │
│                          │ 指导 AI 怎么用工具             │
│  ┌───────────────────────▼─────────────────────────┐     │
│  │  9 个 MCP 工具                                   │     │
│  │  搜索 / 浏览 / 阅读 / 搜索代码 / 历史 / 管理     │     │
│  └───────────┬───────────────────────────┬─────────┘     │
│              │                           │               │
│ ┌────────────▼───────────┐   ┌───────────▼──────────┐    │
│ │  GitHub REST API       │   │  SQLite + FTS5       │    │
│ │  + GitHub 搜索页兜底   │   │  本地代码知识库       │    │
│ │  零 git clone          │   │  Trigram 全文搜索     │    │
│ └────────────────────────┘   └──────────────────────┘    │
│                                                           │
└───────────────────────────────────────────────────────────┘

なぜFTS5で、ベクトルデータベースではないのか？

私たちの解法：二段階検索。 まずGitHub Searchで正しいリポジトリを見つけ（「どのプロジェクトが参考になるか」を解決）、次にFTS5でリポジトリ内のコードを正確に検索（「具体的な実装はどこか」を解決）。

ベクトル検索？コードの再利用というユースケースでは、過剰にマーケティングされていることが多いです。 コードを検索するとき、あなたの頭の中にあるのは「sessionmakerの使い方」「JWTミドルウェアの書き方」であって、「認証に意味的に近いもの」ではありません。

類似プロジェクトとの比較

違いを一言で：

• codedb / codebase-rag = ローカルコードを検索するツール

• 公式GitHub MCP = GitHubの万能ツールボックス

• github-code-rag = GitHubのコードを流用するための専用ツール + おまけの要件分析方法論

プロジェクト構造

├── server/
│   └── mcp_server.py          # MCP 服务器 + 系统提示词
├── github/
│   └── connector.py           # GitHub API 封装（纯 urllib，零依赖）
├── core/
│   ├── models.py              # 数据模型
│   └── retrieval_engine.py    # FTS5 搜索引擎
├── storage/
│   └── sqlite_storage.py      # SQLite + FTS5 + WAL + 触发器同步
├── tests/
│   ├── test_retrieval.py
│   └── test_storage.py
├── .well-known/mcp.json       # SSE 模式配置
└── pyproject.toml

開発

# 克隆
git clone https://github.com/suyu-creator/github-code-rag-mcp.git
cd github-code-rag-mcp

# 安装依赖
uv sync

# 运行测试
uv run pytest

# 手动启动（stdio 模式）
uv run github-code-rag

環境変数：

GITHUB_TOKEN=ghp_xxx           # GitHub API Token（推荐）
CODE_RAG_DATA_DIR=~/.code-rag  # 数据存储目录

FAQ

対応しているMCPクライアントは？

MCPプロトコルに対応しているすべてのクライアント — Claude Code、Claude Desktop、Cursor、Windsurf、Cline、Codex、Gemini CLI、OpenCode… MCPサーバーを設定できるものであれば何でも使えます。

私のコードはアップロードされますか？

されません。すべてのインデックスはローカルのSQLiteに保存されます。GitHub APIは公開リポジトリの読み取りにのみ使用され、あなたのコードが外部に送信されることはありません。

なぜgh CLIを直接使わないのですか？

MCPツールはAIに対して透過的である必要があるためです — AIはあなたがどのCLIをインストールしているかを知る必要はなく、単にツールを呼び出せばよいのです。また、純粋なPython実装で、システム依存がゼロです。

GitHub APIのレート制限に達したらどうなりますか？

自動的にGitHub公式検索ページにフォールバックします。無料無制限で、追加設定は不要です。体験は多少劣りますが、使用できなくなることはありません。

ベクトル検索を追加する予定はありますか？

可能性はありますが、現在の優先順位は高くありません。私たちの位置づけは「再利用に適したコードを素早く見つける」ことであり、FTS5 + GitHub Searchの二段階検索で90%のユースケースをカバーできます。コード再利用のシナリオにおけるベクトル検索の実際のメリットは、マーケティングで謳われているほど大きくありません。

コントリビューション

• バグを発見 → Issueを立てる

• 新しいアイデア → まずIssueで議論

• コードの貢献 → Fork + PR

• 気に入ったら → スターを付けて、多くの人に知ってもらう

English

In One Sentence

An MCP server that lets your AI search and reuse code from GitHub in real time. Writing auth? Search first. Writing middleware? Search first. Writing payment integration? Search first. Before AI writes any code, it finds the best implementation on GitHub — no reinventing the wheel. Also includes a "requirements analysis Agent" methodology so AI researches before building, no guessing.

The Problem

Does this sound familiar?

"Needed an auth module, spent 30 mins Googling, found code of questionable quality."

"There are great implementations on GitHub, but the AI never searches — it just writes from scratch."

"Every new feature feels like reinventing the wheel when answers are everywhere."

The problem is how AI codes today.

Current: AI wants to write → guesses from memory → wrong → rewrite → still wrong

Better: AI wants to write → searches GitHub → finds the best → reuses → tweaks → done

github-code-rag puts GitHub inside your AI's toolbox. Search first, reuse second.

Core Capabilities

🔥 Real-time GitHub code search & reuse

Sorted by stars, finds the most mature projects first. Filter by language and star count.

User: Write a FastAPI database connection module
    ↓
AI: search_github("fastapi sqlalchemy database stars:>1000")
AI: read_github_file("tiangolo/fastapi", "docs_src/sql_app/main.py")
AI: search_code("create_engine sessionmaker")
    ↓
AI: I referenced the FastAPI official example, here you go:

# Source: tiangolo/fastapi/docs_src/sql_app/main.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
...

No browser switching, no cloning repos, no dozens of tabs. Your AI searches GitHub on the fly while coding, finds the best implementation, reuses it.

📚 Read code auto-indexes, gets better over time

All read repos go into a local FTS5 full-text index. Next time you search for related code, results come back in milliseconds.

→ search_code("jwt authentication middleware")
  Found 47 matches across 12 indexed repos:
  - fastapi/.../auth.py:35  JWT bearer middleware
  - django/.../auth.py:128  Token authentication
  - ...

The more you use it, the bigger your local code knowledge base gets, the faster AI codes.

🔄 GitHub API + official search page dual fallback

• GitHub Search API: highest quality, sorted by stars (60 req/hr free, 5000 with Token)

• GitHub official search page fallback: free unlimited quota, auto-degrade on rate limit

• Zero git clone: all via REST API, no local disk bloat

🧠 Bonus: Requirements Analysis Agent

The system prompt hardcodes a workflow so AI doesn't jump straight into coding. It searches similar projects first, asks clarifying questions based on real examples, and only starts building after confirmation.

User: I want to build a blog system
    ↓
AI: [searched 10 relevant projects]
    Do you want a standalone blog (like Hugo/Hexo) or a multi-user platform?
     - Standalone blog (simple, great SEO)
     - Multi-user platform (complex features, needs admin backend)
     - Recommend based on GitHub projects

Think of it as "a senior engineer's methodology — included for free." You don't have to use it. The code search alone is worth it.

⚡ Zero git clone · Zero vector DB · Only 1 dependency

• All via GitHub REST API — no repo cloning needed

• SQLite + FTS5 full-text index — no vector DB or embeddings

• Runtime depends only on mcp>=1.0, everything else is Python stdlib

• Startup < 1 second, memory < 50MB

With vs Without

クイックスタート

1. インストール

# Recommended: pipx (isolated environment)
pipx install github-code-rag

# Or uv
uv tool install github-code-rag

# Or pip
pip install github-code-rag

2. トークン設定（推奨、必須ではない）

export GITHUB_TOKEN=ghp_your_token_here

トークンなしでも動作します — 内蔵のGitHub公式検索ページフォールバックにより、無料で無制限です。 トークンを使用すると、GitHub APIクォータが60 req/hr → 5000 req/hrになります。

3. AIクライアントの設定

以下の「クライアント設定」セクションを参照してください。

4. 試してみる

インストール後、AIに次のように指示します：

「FastAPI JWT認証ミドルウェアを書いてください。まずGitHubを検索して、参照するのに最適な実装を見つけてください。」

コードを書く前にGitHubを検索するかどうかを確認してください。

クライアント設定

すべての設定はstdioモードを使用します。設定後はクライアントを再起動してください。 インストールパスが不明な場合：which github-code-rag（macOS/Linux）または where github-code-rag（Windows）を実行してください。

Claude Code

~/.claude.json を編集し、以下を追加：

{
  "mcpServers": {
    "github-code-rag": {
      "command": "github-code-rag",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Claude Desktop

設定 → 開発者 → 設定を編集、以下を追加：

{
  "mcpServers": {
    "github-code-rag": {
      "command": "github-code-rag"
    }
  }
}

• macOS設定パス：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows設定パス：%APPDATA%\Claude\claude_desktop_config.json

Cursor

プロジェクトレベル（現在のプロジェクトのみ）：プロジェクトルートに .cursor/mcp.json を作成：

{
  "mcpServers": {
    "github-code-rag": {
      "command": "github-code-rag"
    }
  }
}

グローバル：設定 → MCP → 新しいサーバーを追加 → Stdio → github-code-rag を入力

Windsurf

設定 → MCPサーバー → MCPサーバーを追加、stdioモードを選択、コマンド：

github-code-rag

設定ファイルの場所：

• macOS：~/.codeium/windsurf/mcp_config.json

• Windows：%APPDATA%\..\Roaming\Codeium\Windsurf\mcp_config.json

Cline / Roo Code

設定 → MCPサーバー → 新しいMCPサーバーを追加 → ローカル実行可能ファイル、以下を入力：

Command: github-code-rag

または設定ファイルを直接編集：

• Cline：~/.cline/mcp.json

• Roo Code：~/.roo-code/mcp.json

Codex CLI

~/.codex/config.toml を編集し、以下を追加：

[mcp_servers.github-code-rag]
command = "github-code-rag"

OpenCode

OpenCode設定のmcpサーバーセクションを編集：

{
  "mcpServers": {
    "github-code-rag": {
      "command": "github-code-rag"
    }
  }
}

MCP互換のクライアントであればどれでも動作します。上記にないクライアントの場合も、基本的な設定は同じです — command を github-code-rag に指定してください。

ツール一覧

仕組み

┌───────────────────────────────────────────────────────────┐
│                    Your AI Client                         │
│  (Claude Code / Cursor / Codex / Claude Desktop / ...)   │
└───────────────────────────┬───────────────────────────────┘
                            │ MCP protocol (stdio)
┌───────────────────────────▼───────────────────────────────┐
│                                                           │
│  ┌─────────────────────────────────────────────────┐     │
│  │  System Prompt (Requirements Analysis Agent)    │     │
│  │    · Search first · Iterative narrowing         │     │
│  │    · Reuse-first · One question at a time       │     │
│  └───────────────────────┬─────────────────────────┘     │
│                          │ Guides AI tool usage           │
│  ┌───────────────────────▼─────────────────────────┐     │
│  │  9 MCP Tools                                     │     │
│  │  search / browse / read / code search / history │     │
│  └───────────┬───────────────────────────┬─────────┘     │
│              │                           │               │
│ ┌────────────▼───────────┐   ┌───────────▼──────────┐    │
│ │  GitHub REST API       │   │  SQLite + FTS5       │    │
│ │  + GitHub search page  │   │  Local code KB       │    │
│ │  Zero git clone        │   │  Trigram FTS         │    │
│ └────────────────────────┘   └──────────────────────┘    │
│                                                           │
└───────────────────────────────────────────────────────────┘

なぜFTS5で、ベクターデータベースではないのか？

私たちのアプローチ：二段階検索。 まずGitHub検索を使用して適切なリポジトリを見つけ（「どのプロジェクトを参照する価値があるか」）、次にFTS5を使用してリポジトリ内のコードを特定します（「実装はどこにあるか」）。

ベクター検索？コード再利用においては、過大評価されていることがよくあります。 コードを検索するとき、あなたは「sessionmakerの使い方」や「JWTミドルウェアの書き方」を考えます — 「認証と意味的に類似したもの」ではありません。

比較

一言で言うと：

• codedb / codebase-rag = ローカルコード検索ツール

• 公式GitHub MCP = GitHubのためのスイスアーミーナイフ

• github-code-rag = GitHubコード再利用専用 + おまけの方法論エージェント

プロジェクト構造

├── server/
│   └── mcp_server.py          # MCP server + system prompt
├── github/
│   └── connector.py           # GitHub API wrapper (pure urllib, zero deps)
├── core/
│   ├── models.py              # Data models
│   └── retrieval_engine.py    # FTS5 search engine
├── storage/
│   └── sqlite_storage.py      # SQLite + FTS5 + WAL + trigger sync
├── tests/
│   ├── test_retrieval.py
│   └── test_storage.py
├── .well-known/mcp.json       # SSE mode config
└── pyproject.toml

開発

# Clone
git clone https://github.com/suyu-creator/github-code-rag-mcp.git
cd github-code-rag-mcp

# Install dependencies
uv sync

# Run tests
uv run pytest

# Manual start (stdio mode)
uv run github-code-rag

環境変数：

GITHUB_TOKEN=ghp_xxx           # GitHub API Token (recommended)
CODE_RAG_DATA_DIR=~/.code-rag  # Data storage directory

FAQ

どのMCPクライアントをサポートしていますか？

すべてのMCP互換クライアント — Claude Code、Claude Desktop、Cursor、Windsurf、Cline、Codex、Gemini CLI、OpenCode… MCPサーバーを設定できるクライアントであればどれでも動作します。

私のコードはアップロードされますか？

いいえ。すべてのインデックスはローカルSQLiteに保存されます。GitHub APIは公開リポジトリのみを読み取ります。あなたのコードがマシンの外に出ることはありません。

なぜ単にgh CLIを使わないのですか？

MCPツールはAIに対して透過的であるべきだからです — インストールされているCLIを知る必要はなく、ツールを呼び出すだけです。さらに、純粋なPython実装で、システム依存関係はゼロです。

GitHub APIのレート制限に達した場合はどうなりますか？

自動的にGitHub公式検索ページにダウングレードします。無料、無制限クォータ、追加設定は不要です。エクスペリエンスは若干低下しますが、動作が停止することはありません。

ベクター検索を追加しますか？

可能性はありますが、現在の優先事項ではありません。私たちの焦点は「再利用する適切なコードを素早く見つけること」です。二段階検索（GitHub検索 + FTS5）ですでに90%のユースケースをカバーしています。コード再利用におけるベクター検索の実際の利点は、マーケティングの主張ほど大きくありません。

コントリビューション

• バグを発見 → Issueを開く

• 新しいアイデア → まずIssueで議論

• コードコントリビューション → Fork + PR

• 便利だと思ったら → スターを付けて、より多くの人が見つけられるようにしてください