codebase-rag-mcp
Provides tools for retrieving and searching codebases, enabling AI agents to fetch code snippets, search for symbols, and get file outlines for context in code generation or analysis tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codebase-rag-mcp search for the authenticate function in auth.ts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Codebase RAG MCP
A local-first, no API Key codebase retrieval MCP Server. It scans specified repositories, chunks code by code windows, and performs hybrid ranking via BM25, symbol names, file paths, and exact matches. It can be directly connected to Codex and also provides standard search / fetch tools for ChatGPT knowledge retrieval scenarios.
Features
Uses
git ls-filespreferentially, respects nested.gitignorefiles of the repository; non-Git directories use filesystem scanning.Supports common text code formats such as TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, C#, Ruby, Shell, SQL, Markdown, Vue, Svelte.
Automatically splits camelCase, snake_case, and path words, supports common Chinese code query expansions, e.g., "用户登录认证".
Returns precise file paths, line numbers, code snippets with line numbers, match reasons, and stable IDs for further reading.
Path reading is restricted to the configured repository root; symbols links, binaries, secrets, environment variable files, minified code, and large files are skipped by default.
Supports both local
stdioand stateless Streamable HTTP/mcp.
Related MCP server: mcplens
Quick Start
Requires Node.js 20 or higher.
Get the project from GitHub:
git clone https://github.com/sudoriaa/codebase-rag-mcp.git
cd codebase-rag-mcpInstall dependencies and build:
npm install
npm run build
node dist/cli.js --root C:/path/to/your-repositoryThe last command starts the stdio MCP Server, which waits for an MCP client to connect, so it is normal for the terminal to keep running.
Connecting to Codex
Put the following into the user-level %USERPROFILE%/.codex/config.toml, or a trusted repository's .codex/config.toml:
[mcp_servers.codebase-rag]
command = "C:/Program Files/nodejs/node.exe"
args = [
"C:/absolute/path/codebase-rag-mcp/dist/cli.js",
"--root",
"C:/absolute/path/your-repository"
]
cwd = "C:/absolute/path/codebase-rag-mcp"
startup_timeout_sec = 60
tool_timeout_sec = 120It is recommended to use / for Windows TOML paths. Only fill in the executable for command, and put other parameters in args respectively. The PATH inherited by desktop applications may differ from PowerShell, so it is recommended to use the absolute path of node.exe for long-term use.
You can also register via the CLI:
codex mcp add codebase-rag -- "C:\Program Files\nodejs\node.exe" "C:\absolute\path\codebase-rag-mcp\dist\cli.js" --root "C:\absolute\path\your-repository"
codex mcp get codebase-rag --jsonAfter configuration, restart the Codex desktop application or IDE extension. See examples/codex-config.toml for an example configuration.
Starting HTTP MCP
node dist/cli.js --root C:/path/to/your-repository --transport http --host 127.0.0.1 --port 3000Endpoints:
MCP:
http://127.0.0.1:3000/mcpHealth check:
http://127.0.0.1:3000/healthReference source file:
http://127.0.0.1:3000/source/:documentId
By default, it only listens to the local machine. When deploying to other machines, TLS, authentication, and access control should be added at the reverse proxy layer, and use --public-base-url to set the canonical address accessible by the model.
When listening directly on 0.0.0.0 or other non-local addresses, the service requires a Bearer Token:
$env:CODEBASE_MCP_TOKEN = "replace-with-a-long-random-token"
node dist/cli.js --root C:/path/to/your-repository --transport http --host 0.0.0.0 --port 3000The client then needs to send Authorization: Bearer <token> for /mcp and /health. The reference addresses returned by the service will automatically include an HMAC signature, so users can directly open the corresponding /source link; manually accessing unsigned /source addresses still requires the Bearer Token. When publishing via a local reverse proxy, the service can continue to listen on 127.0.0.1, and the proxy handles external authentication.
MCP Tools
Tool | Purpose |
| Standard document search, returns |
| Gets the full file based on the ID returned by |
| Hybrid retrieval of code snippets, filterable by path, language, symbol type, and test files |
| Gets context based on chunk ID, up to 200 lines of expansion |
| Finds definitions of classes, functions, methods, interfaces, types, and enums |
| Returns file imports and symbol outline |
| Views index statistics and skip reasons |
| Rescans files and rebuilds the in-memory index after file changes |
Recommended calling order:
Use
search_codeto find implementations and related snippets.Use
get_code_contextto expand high-scoring snippets.Use
find_symbolfor precise definition location.Only use
fetchwhen the full file is truly necessary.
Search Methodology
The index runs entirely in local memory:
Code files are sliced into chunks of up to 120 lines with a 20-line overlap.
Symbols like class, interface, type, enum, function, method are extracted from common language declarations.
The body text uses BM25 retrieval; symbols and paths are ranked separately.
Reciprocal-rank fusion is used to combine scores from body text, symbols, paths, and exact matches.
By default, at most two snippets are returned per file to avoid filling up results with duplicate boilerplate code.
This version has no external vector database and does not upload source code. For large-scale multi-repository, cross-language semantic retrieval, embedding retrieval or rerankers can be added before or after the existing CodebaseIndex.search, without changing the MCP tool contract.
Configuration
--root PATH
--transport stdio|http
--host HOST
--port PORT
--public-base-url URL
--max-file-bytes N
--max-files NThe corresponding environment variables are:
CODEBASE_ROOT
CODEBASE_TRANSPORT
CODEBASE_HOST
CODEBASE_PORT
CODEBASE_PUBLIC_BASE_URL
CODEBASE_MCP_TOKEN
CODEBASE_MAX_FILE_BYTES
CODEBASE_MAX_FILESDefault single file size limit is 1 MiB, file count limit is 20,000.
Development and Verification
npm run build
npm testTests cover index building, .gitignore, Chinese query expansion, symbol and path filtering, path traversal, standard search/fetch, in-memory MCP, real stdio subprocesses, and Streamable HTTP.
The MCP Inspector can also directly inspect the HTTP service:
npx @modelcontextprotocol/inspectorThen select Streamable HTTP and fill in http://127.0.0.1:3000/mcp.
The implementation follows the OpenAI Official MCP Server Guide and the standard search / fetch data shapes.
Current Boundaries
The index is rebuilt after a process restart; there is no persistent cache.
Git repositories fully respect Git ignore rules; non-Git directories currently read the root
.gitignore.Symbol extraction uses lightweight declaration parsing and is not equivalent to a full compiler AST.
Call
refresh_indexafter file changes; file watching is not enabled in the current version.
License
MIT
Available Tools
8 toolsfetchFetch repository fileARead-only
Fetch the complete text and metadata for a document ID returned by search or search_code.
Inputs: id (required). Returns: id, url, text, title, +1 more
find_symbolFind symbolARead-only
Find class, function, method, interface, type, enum, module, or variable definitions by identifier.
Inputs: name (required), kind, topK, pathGlob. Returns: results
get_code_contextGet code contextARead-only
Retrieve a matched code chunk with configurable surrounding lines. Use the chunkId returned by search_code.
Inputs: chunkId (required), contextLines. Returns: url, path, text, chunkId, +6 more
get_file_outlineGet file outlineARead-only
Return imports and symbol definitions for an indexed repository-relative path.
Inputs: path (required). Returns: url, path, imports, symbols, +2 more
get_index_statusGet index statusARead-only
Return repository root, index time, counts, duration, and skipped-file statistics.
Inputs: no named parameters. Returns: root, skipped, fileCount, indexedAt, +3 more
refresh_indexRefresh code indexA
Rescan the configured repository and rebuild the in-memory retrieval index after files change. Repository files are never modified.
Inputs: no named parameters. Returns: root, skipped, fileCount, indexedAt, +3 more
searchSearch repository documentsARead-only
Search indexed repository files. This standard read-only search tool is compatible with ChatGPT company knowledge and returns document IDs for fetch.
Inputs: query (required). Returns: results
search_codeSearch codeARead-only
Run hybrid BM25, symbol, path, and exact-match retrieval over code chunks. Use this first for implementation, behavior, error, and call-site questions.
Inputs: query (required), topK, pathGlob, languages, +2 more. Returns: query, results
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose. search and search_code are differentiated as general text search vs. code-specific retrieval, with paired fetch and get_code_context for results. find_symbol, get_file_outline, get_index_status, and refresh_index each serve unique, non-overlapping functions.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., search_code, get_code_context, find_symbol). Even simple verbs like search and fetch fit the pattern. No mixing of conventions.
With 8 tools, the server is well-scoped for a codebase RAG assistant. The set covers search, retrieval, symbol lookup, file outline, indexing status, and index refresh without unnecessary bloat or excessive minimalism.
Core workflows are well-covered: search (general and code), retrieve (full doc and chunk), symbol resolution, file outline, and index management. Minor gaps like listing all files or a 'get_by_path' could exist, but the current set handles most agent needs effectively.
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server and CLI tool that transforms codebases into AI-ready context through semantic search, call graph analysis, and incremental indexing. It enables AI assistants to perform hybrid vector and keyword searches to understand complex repository structures and cross-file relationships.3526 npm3MIT
- AlicenseNot gradedqualityBmaintenanceA local MCP server that provides AI coding assistants with semantic search capabilities over codebases. It indexes code using local embeddings and exposes tools for efficient code retrieval, saving tokens and improving response quality.31 npm4MIT
- AlicenseAqualityDmaintenanceA local-first MCP server that enables AI tools to safely inspect and search code repositories, providing indexing, deterministic BM25 search, code outlining, and context bundles without code modification.91MIT
- AlicenseNot gradedqualityDmaintenanceA self-hosted MCP server that indexes your codebase and provides AI assistants with deep context including file tree, full-text search, git history, dependencies, and stack detection, all without sending your code to third parties.5 npm1MIT