github-code-rag-mcp

En una frase

Un servidor MCP que permite a tu IA buscar y reutilizar código de GitHub en tiempo real. ¿Escribiendo autenticación? Busca primero. ¿Middleware? Busca primero. ¿Pagos? Busca primero. Antes de que la IA escriba una línea de código, encuentra la mejor implementación en GitHub — prohibido reinventar la rueda. Además incluye una metodología de "Agente de análisis de requisitos" para que la IA investigue antes de construir, sin adivinar.

Related MCP server: MCP Code Intelligence

El problema

¿Te suena familiar?

"Necesitaba un módulo de autenticación, pasé 30 minutos buscando en Google y encontré código de calidad dudosa."

"Hay implementaciones excelentes en GitHub, pero la IA nunca busca — simplemente escribe desde cero."

"Cada nueva función se siente como reinventar la rueda cuando las respuestas están por todas partes."

El problema es cómo programa la IA hoy.

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

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

github-code-rag pone GitHub dentro de la caja de herramientas de tu IA. Busca primero, reutiliza después.

Capacidades principales

🔥 Búsqueda en tiempo real de GitHub y reutilización de código

Ordenado por estrellas, encuentra primero los proyectos más maduros. Filtra por lenguaje y número de estrellas.

用户：帮我写个 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
...

Sin cambiar al navegador, sin clonar repositorios, sin decenas de pestañas. Tu IA busca en GitHub sobre la marcha mientras programa, encuentra la mejor implementación y la reutiliza.

📚 El código leído se indexa automáticamente, mejora con el tiempo

Todos los repositorios leídos van a un índice de texto completo FTS5 local. La próxima vez que busques código relacionado, los resultados llegan en milisegundos.

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

Cuanto más lo uses, más grande será tu base de conocimiento local de código, más rápido programará la IA.

🔄 API de GitHub + página de búsqueda oficial como respaldo doble

• API de búsqueda de GitHub: máxima calidad, ordenado por estrellas (60 solicitudes/hora gratis, 5000 con Token)

• Página de búsqueda oficial de GitHub como respaldo: cuota ilimitada gratuita, degradación automática ante límite de tasa

• Sin clonar con git: todo a través de la API REST, sin ocupar espacio en disco local

🧠 Bonus: Agente de análisis de requisitos

El prompt del sistema codifica un flujo de trabajo para que la IA no se lance directamente a programar. Primero busca proyectos similares, hace preguntas aclaratorias basadas en ejemplos reales, y solo comienza a construir después de la confirmación.

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

Puedes pensar en ello como "la metodología de un ingeniero senior — incluida gratis". No tienes que usarla. La búsqueda de código ya vale la pena.

⚡ Sin clonar con git · Sin base de datos vectorial · Solo 1 dependencia

• Todo a través de la API REST de GitHub — no es necesario clonar repositorios

• SQLite + índice de texto completo FTS5 — no se necesita base de datos vectorial ni embeddings

• En tiempo de ejecución solo depende de mcp>=1.0, todo lo demás es biblioteca estándar de Python

• Inicio en < 1 segundo, memoria < 50MB

Con vs. Sin

Inicio rápido

1. Instalación

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

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

# 或者 pip
pip install github-code-rag

2. Configurar Token (opcional pero recomendado)

export GITHUB_TOKEN=ghp_your_token_here

Sin Token también funciona — incluye respaldo de la página de búsqueda oficial de GitHub, cuota ilimitada gratuita. Con Token, la cuota de la API de GitHub pasa de 60 solicitudes/hora → 5000 solicitudes/hora.

3. Configurar en tu cliente de IA

Consulta la sección "Configuración del cliente" a continuación.

4. Pruébalo

Una vez configurado, dile a tu IA:

"Ayúdame a escribir un middleware de autenticación JWT para FastAPI, primero busca en GitHub la mejor implementación de referencia"

Mira si primero busca en GitHub y luego escribe basándose en el código encontrado.

Configuración del cliente

Las siguientes configuraciones son para modo stdio. Reinicia el cliente después de configurar. ¿No estás seguro de la ruta de instalación? Ejecuta which github-code-rag (macOS/Linux) o where github-code-rag (Windows) para verla.

Claude Code

Edita ~/.claude.json, añade:

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

Claude Desktop

Abre Configuración → Developer → Edit Config, añade:

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

• Ruta del archivo de configuración en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Ruta del archivo de configuración en Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor

Configuración a nivel de proyecto (solo para el proyecto actual): crea .cursor/mcp.json en la raíz del proyecto:

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

Configuración global: Ajustes → MCP → Add new server → Stdio → Introduce github-code-rag

Windsurf

Ajustes → MCP Servers → Add MCP Server, selecciona modo stdio, comando:

github-code-rag

El archivo de configuración suele estar en:

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

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

Cline / Roo Code

Ajustes → MCP Servers → Add new MCP Server → Local executable, introduce:

Command: github-code-rag

O edita directamente el archivo de configuración:

• Cline: ~/.cline/mcp.json

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

Codex CLI

Edita ~/.codex/config.toml, añade:

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

OpenCode

Edita la sección de servidores MCP en el archivo de configuración de OpenCode:

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

Todos los clientes que soporten el protocolo MCP pueden usarlo. Si tu cliente no está en la lista anterior, la configuración es básicamente la misma: apunta el comando a github-code-rag.

Lista de herramientas

Cómo funciona

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

¿Por qué FTS5 y no una base de datos vectorial?

Nuestra solución: búsqueda en dos fases. Primero usamos la búsqueda de GitHub para encontrar el repositorio correcto (resuelve "qué proyecto merece la pena consultar"), luego usamos FTS5 para buscar código con precisión dentro del repositorio (resuelve "dónde está la implementación concreta").

¿Búsqueda vectorial? Para el escenario de reutilización de código, a menudo es una solución sobrevalorada. Cuando buscas código, piensas en "cómo se usa sessionmaker" o "cómo escribir un middleware JWT", no en "cosas semánticamente cercanas a autenticación".

Comparación con proyectos similares

Resumen de diferencias en una frase:

• codedb / codebase-rag = herramientas para buscar código local

• MCP oficial de GitHub = caja de herramientas multifunción de GitHub

• github-code-rag = herramienta especializada para copiar código de GitHub + metodología de análisis de requisitos incluida

Estructura del proyecto

├── 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

Desarrollo

# 克隆
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

Variables de entorno:

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

FAQ

¿Qué clientes MCP son compatibles?

Todos los que soporten el protocolo MCP — Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Codex, Gemini CLI, OpenCode… Si puede configurar un servidor MCP, funciona.

¿Se subirá mi código?

No. Todos los índices se almacenan en SQLite local. La API de GitHub solo se usa para leer repositorios públicos; tu código no se envía.

¿Por qué no usar directamente gh CLI?

Porque las herramientas MCP deben ser transparentes para la IA — la IA no necesita saber qué CLI tienes instalado, solo necesita llamar a la herramienta. Además, es una implementación pura en Python, sin dependencias del sistema.

¿Qué pasa si la API de GitHub tiene límite de tasa?

Degrada automáticamente a la página de búsqueda oficial de GitHub, cuota ilimitada gratuita, sin necesidad de configuración adicional. La experiencia es un poco peor, pero no deja de funcionar.

¿Añadirán búsqueda vectorial?

Quizás, pero no es la prioridad actual. Nuestro enfoque es "encontrar rápidamente el código correcto para reutilizar"; la búsqueda en dos fases de FTS5 + búsqueda de GitHub ya cubre el 90% de los escenarios. La búsqueda vectorial en el escenario de reutilización de código no tiene el beneficio real que promete el marketing.

Contribuir

• Encontrar un error → Abrir un Issue

• Tener una idea nueva → Abrir un Issue primero para discutir

• Contribuir código → Fork + PR

• Si te gusta → Dale una estrella para que más gente lo vea

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

Inicio Rápido

1. Instalación

# 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. Configurar Token (opcional pero recomendado)

export GITHUB_TOKEN=ghp_your_token_here

Funciona sin token: tiene retroceso integrado a la página de búsqueda oficial de GitHub, gratuito e ilimitado. Con un token, la cuota de la API de GitHub pasa de 60 solicitudes/hora → 5000 solicitudes/hora.

3. Configurar tu cliente de IA

Consulta la sección "Configuración del Cliente" a continuación.

4. Pruébalo

Después de la instalación, dile a tu IA:

"Escribe un middleware de autenticación JWT para FastAPI. Primero busca en GitHub la mejor implementación para referenciar."

Observa si busca en GitHub antes de escribir código.

Configuración del Cliente

Todas las configuraciones utilizan el modo stdio. Reinicia tu cliente después de la configuración. ¿No sabes la ruta de instalación? Ejecuta which github-code-rag (macOS/Linux) o where github-code-rag (Windows).

Claude Code

Edita ~/.claude.json, añade:

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

Claude Desktop

Ajustes → Desarrollador → Editar Config, añade:

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

• Ruta de configuración en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Ruta de configuración en Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor

A nivel de proyecto (solo proyecto actual): crea .cursor/mcp.json en la raíz del proyecto:

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

Global: Ajustes → MCP → Añadir nuevo servidor → Stdio → introduce github-code-rag

Windsurf

Ajustes → Servidores MCP → Añadir Servidor MCP, elige modo stdio, comando:

github-code-rag

Ubicaciones de archivos de configuración:

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

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

Cline / Roo Code

Ajustes → Servidores MCP → Añadir nuevo Servidor MCP → Ejecutable local, introduce:

Command: github-code-rag

O edita los archivos de configuración directamente:

• Cline: ~/.cline/mcp.json

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

Codex CLI

Edita ~/.codex/config.toml, añade:

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

OpenCode

Edita la sección de servidores mcp en la configuración de OpenCode:

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

Cualquier cliente compatible con MCP funciona. Si tu cliente no está listado arriba, la configuración es básicamente la misma: apunta command a github-code-rag.

Lista de Herramientas

Cómo Funciona

┌───────────────────────────────────────────────────────────┐
│                    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         │    │
│ └────────────────────────┘   └──────────────────────┘    │
│                                                           │
└───────────────────────────────────────────────────────────┘

¿Por qué FTS5 y no bases de datos vectoriales?

Nuestro enfoque: búsqueda en dos fases. Primero usa la Búsqueda de GitHub para encontrar los repositorios adecuados ("qué proyecto vale la pena referenciar"), luego usa FTS5 para localizar el código dentro de los repositorios ("dónde está la implementación").

¿Búsqueda vectorial? Para reutilización de código, a menudo es una solución sobrevalorada. Cuando buscas código, piensas "cómo usar sessionmaker" o "cómo escribir un middleware JWT" — no "cosas semánticamente similares a autenticación."

Comparación

En una frase:

• codedb / codebase-rag = herramientas para buscar código local

• MCP Oficial de GitHub = navaja suiza para GitHub

• github-code-rag = construido específicamente para reutilizar código de GitHub + Agente de metodología adicional

Estructura del Proyecto

├── 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

Desarrollo

# 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

Variables de entorno:

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

Preguntas Frecuentes

¿Qué clientes MCP son compatibles?

Todos los clientes compatibles con MCP: Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Codex, Gemini CLI, OpenCode… cualquier cliente que pueda configurar un servidor MCP funciona.

¿Mi código será subido?

No. Todos los índices se almacenan en SQLite local. La API de GitHub solo lee repositorios públicos. Tu código nunca sale de tu máquina.

¿Por qué no usar simplemente gh CLI?

Porque las herramientas MCP deben ser transparentes para la IA — no necesita saber qué CLI tienes instalada, simplemente llama a las herramientas. Además, implementación pura en Python, cero dependencias del sistema.

¿Qué pasa si la API de GitHub está limitada por tasa?

Degrada automáticamente a la página de búsqueda oficial de GitHub. Gratuito, cuota ilimitada, sin configuración adicional necesaria. La experiencia es ligeramente degradada, pero nunca deja de funcionar.

¿Añadirán búsqueda vectorial?

Quizás, pero no es la prioridad actual. Nuestro enfoque es "encontrar rápidamente el código correcto para reutilizar." La búsqueda en dos fases (Búsqueda de GitHub + FTS5) ya cubre el 90% de los casos de uso. El beneficio real de la búsqueda vectorial para reutilización de código no es tan grande como afirman los responsables de marketing.

Contribuciones

• Encontraste un error → abre un Issue

• Nueva idea → abre un Issue para discutir primero

• Contribución de código → Fork + PR

• Te resulta útil → dale estrella, ayuda a que más personas lo descubran