code-index-mcp
The code-index-mcp server is a specialized Model Context Protocol (MCP) server for intelligent code indexing, searching, and analysis that enables AI models to interact with code repositories.
Core Capabilities:
Project Indexing: Recursively scans directories to build a searchable index of code files, automatically ignoring build directories and non-code files
Search Code: Performs intelligent code searches using automatically detected tools (ripgrep, ag, or grep) with options for case sensitivity, context lines, file patterns, and fuzzy matching
Find Files: Locate files matching specific glob patterns within the project
Analyze Files: Generate detailed insights about file structure, including line counts, functions, imports, and complexity metrics
Manage Index: Refresh the project index or clear cached settings
Persistent Storage: Caches indexes for improved performance across sessions
Broad Language Support: Handles various programming languages, web files, database files, and documentation
Integration: Seamlessly integrates with Claude Desktop for enhanced code navigation and analysis
Provides access to git repositories, allowing users to clone projects for code indexing and analysis.
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., "@code-index-mcp search for authentication middleware in the current project"
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.
Code Index MCP
Intelligent code indexing and analysis for Large Language Models
Transform how AI understands your codebase with advanced search, analysis, and navigation capabilities.
Overview
Code Index MCP is a Model Context Protocol server that bridges the gap between AI models and complex codebases. It provides intelligent indexing, advanced search capabilities, and detailed code analysis to help AI assistants understand and navigate your projects effectively.
Perfect for: Code review, refactoring, documentation generation, debugging assistance, and architectural analysis.
Related MCP server: @lex-tools/codebase-context-dumper
Quick Start
🚀 Recommended Setup (Most Users)
The easiest way to get started with any MCP-compatible application:
Prerequisites: Python 3.10+ and uv
Add to your MCP configuration (e.g.,
claude_desktop_config.jsonor~/.claude.json):{ "mcpServers": { "code-index": { "command": "uvx", "args": ["code-index-mcp"] } } }Optional: append
--project-path /absolute/path/to/repoto theargsarray so the server initializes with that repository automatically (equivalent to callingset_project_pathafter startup).Restart your application –
uvxautomatically handles installation and executionStart using (give these prompts to your AI assistant):
Set the project path to /Users/dev/my-react-app Find all TypeScript files in this project Search for "authentication" functions Analyze the main App.tsx fileIf you launch with
--project-path, you can skip the first command above - the server already knows the project location.
Codex CLI Configuration
If you are using Anthropic's Codex CLI, add the server to ~/.codex/config.toml.
On Windows the file lives at C:\Users\<you>\.codex\config.toml:
[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]You can append
--project-path C:/absolute/path/to/repoto theargslist to set the project automatically on startup (same effect as running theset_project_pathtool).
On Windows, uvx needs the standard profile directories to be present.
Keep the environment override in the same block so the MCP starts reliably:
env = {
HOME = "C:\\Users\\<you>",
APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
SystemRoot = "C:\\Windows"
}Linux and macOS already expose the required XDG paths and HOME, so you can usually omit the env
table there.
Add overrides only if you run the CLI inside a restricted container.
FastMCP & Discovery Manifests
Run
fastmcp run fastmcp.jsonto launch the server via FastMCP with the correct source entrypoint and dependency metadata. Pass--project-path(or call theset_project_pathtool after startup) so the index boots against the right repository.Serve or copy
.well-known/mcp.jsonto share a standards-compliant MCP manifest. Clients that support the.well-knownconvention (e.g., Claude Desktop, Codex CLI) can import this file directly instead of crafting configs manually.Publish
.well-known/mcp.llmfeed.jsonwhen you want to expose the richer LLM Feed metadata. It references the samecode-indexserver definition plus documentation/source links, which helps registries present descriptions, tags, and capabilities automatically.
When sharing the manifests, remind consumers to supply --project-path (or to call
set_project_path) so the server indexes the intended repository.
Typical Use Cases
Code Review: "Find all places using the old API"
Refactoring Help: "Where is this function called?"
Learning Projects: "Show me the main components of this React project"
Debugging: "Search for all error handling related code"
Key Features
🔍 Intelligent Search & Analysis
Dual-Strategy Architecture: Specialized tree-sitter parsing for 10 core languages, fallback strategy for 50+ file types
Direct Tree-sitter Integration: No regex fallbacks for specialized languages - fail fast with clear errors
Advanced Search: Auto-detects and uses the best available tool (ugrep, ripgrep, ag, or grep)
Universal File Support: Comprehensive coverage from advanced AST parsing to basic file indexing
File Analysis: Deep insights into structure, imports, classes, methods, and complexity metrics after running
build_deep_index
🗂️ Multi-Language Support
10 Languages with Tree-sitter AST Parsing: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig, Rust
50+ File Types with Fallback Strategy: C/C++, Ruby, PHP, and all other programming languages
Document & Config Files: Markdown, JSON, YAML, XML with appropriate handling
Web Frontend: Vue, React, Svelte, HTML, CSS, SCSS
Java Web & Build: JSP/Tag files (
.jsp,.jspx,.jspf,.tag,.tagx), Grails/GSP (.gsp), Gradle & Groovy builds (.gradle,.groovy),.properties, and Protocol Buffers (.proto)Database: SQL variants, NoSQL, stored procedures, migrations
Configuration: JSON, YAML, XML, Markdown
⚡ Real-time Monitoring & Auto-refresh
File Watcher: Automatic index updates when files change
Cross-platform: Native OS file system monitoring
Smart Processing: Batches rapid changes to prevent excessive rebuilds
Shallow Index Refresh: Watches file changes and keeps the file list current; run a deep rebuild when you need symbol metadata
⚡ Performance & Efficiency
Tree-sitter AST Parsing: Native syntax parsing for accurate symbol extraction
Persistent Caching: Stores indexes for lightning-fast subsequent access
Smart Filtering: Intelligent exclusion of build directories and temporary files
Memory Efficient: Optimized for large codebases
Direct Dependencies: No fallback mechanisms - fail fast with clear error messages
Supported File Types
Languages with Specialized Tree-sitter Strategies:
Python (
.py,.pyw) - Full AST analysis with class/method extraction and call trackingJavaScript (
.js,.jsx,.mjs,.cjs) - ES6+ class and function parsing with tree-sitterTypeScript (
.ts,.tsx) - Complete type-aware symbol extraction with interfacesJava (
.java) - Full class hierarchy, method signatures, and call relationshipsKotlin (
.kt,.kts) - Package-aware symbol extraction with methods and call relationshipsC# (
.cs) - Namespace-aware type/member extraction with call relationshipsGo (
.go) - Struct methods, receiver types, and function analysisRust (
.rs) - Functions, module-aware names, impl methods, structs/enums/traits, and basic call relationshipsObjective-C (
.m,.mm) - Class/instance method distinction with +/- notationZig (
.zig,.zon) - Function and struct parsing with tree-sitter AST
All Other Programming Languages: All other programming languages use the FallbackParsingStrategy which provides basic file indexing and metadata extraction. This includes:
System & Low-Level: C/C++ (
.c,.cpp,.h,.hpp)Object-Oriented: Scala (
.scala), Swift (.swift)Scripting & Dynamic: Ruby (
.rb), PHP (.php), Shell (.sh,.bash)And 40+ more file types - All handled through the fallback strategy for basic indexing
Frameworks & Libraries:
Vue (
.vue)Svelte (
.svelte)Astro (
.astro)
Styling:
CSS (
.css,.scss,.less,.sass,.stylus,.styl)HTML (
.html)
Templates:
Handlebars (
.hbs,.handlebars)EJS (
.ejs)Pug (
.pug)FreeMarker (
.ftl)Mustache (
.mustache)Liquid (
.liquid)ERB (
.erb)
SQL Variants:
Standard SQL (
.sql,.ddl,.dml)Database-specific (
.mysql,.postgresql,.psql,.sqlite,.mssql,.oracle,.ora,.db2)
Database Objects:
Procedures & Functions (
.proc,.procedure,.func,.function)Views & Triggers (
.view,.trigger,.index)
Migration & Tools:
Migration files (
.migration,.seed,.fixture,.schema)Tool-specific (
.liquibase,.flyway)
NoSQL & Modern:
Graph & Query (
.cql,.cypher,.sparql,.gql)
Markdown (
.md,.mdx)Configuration (
.json,.xml,.yml,.yaml,.properties)
🛠️ Development Setup
For contributing or local development:
Clone and install:
git clone https://github.com/johnhuang316/code-index-mcp.git cd code-index-mcp uv syncConfigure for local development:
{ "mcpServers": { "code-index": { "command": "uv", "args": ["run", "code-index-mcp"] } } }Debug with MCP Inspector:
npx @modelcontextprotocol/inspector uv run code-index-mcp
If you prefer traditional pip management:
pip install code-index-mcpThen configure:
{
"mcpServers": {
"code-index": {
"command": "code-index-mcp",
"args": []
}
}
}Available Tools
🏗️ Project Management
Tool | Description |
| Initialize indexing for a project directory |
| Rebuild the shallow file index after file changes |
| Generate the full symbol index used by deep analysis |
| View current project configuration and status |
Run build_deep_index when you need symbol-level data; the default shallow index powers quick file discovery.
🔍 Search & Discovery
Tool | Description |
| Smart search with literal-by-default matching, optional |
| Locate files using glob patterns (e.g., |
| Analyze file structure, functions, imports, and complexity (requires deep index) |
🔄 Monitoring & Auto-refresh
Tool | Description |
| Check file watcher status and configuration |
| Enable/disable auto-refresh and configure settings |
🛠️ System & Maintenance
Tool | Description |
| Set up storage directory for index data |
| Verify index storage location and permissions |
| Reset all cached data and configurations |
| Re-detect available search tools (ugrep, ripgrep, etc.) |
Usage Examples
🎯 Quick Start Workflow
1. Initialize Your Project
Set the project path to /Users/dev/my-react-appAutomatically indexes your codebase and creates searchable cache
2. Explore Project Structure
Find all TypeScript component files in src/componentsUses: find_files with pattern src/components/**/*.tsx
3. Analyze Key Files
Give me a summary of src/api/userService.tsUses: get_file_summary to show functions, imports, and complexity
Tip: run build_deep_index first if you get a needs_deep_index response.
🔍 Advanced Search Examples
Search for all function calls matching "get.*Data" using `regex=True`Finds: getData(), getUserData(), getFormData(), etc. Regex search is opt-in; install a native search tool and use regex=True because the basic fallback stays literal-only.
Find authentication-related functions with fuzzy search for 'authUser'Matches: authenticateUser, authUserToken, userAuthCheck, etc.
Search for "API_ENDPOINT" only in Python filesUses: search_code_advanced with literal matching and file_pattern: "*.py" (defaults to 10 matches; use max_results to expand or start_index to page)
Configure automatic index updates when files changeUses: configure_file_watcher to enable/disable monitoring and set debounce timing
I added new components, please refresh the project indexUses: refresh_index to update the searchable cache
Troubleshooting
🔄 Auto-refresh Not Working
If automatic index updates aren't working when files change, try:
pip install watchdog(may resolve environment isolation issues)Use manual refresh: Call the
refresh_indextool after making file changesCheck file watcher status: Use
get_file_watcher_statusto verify monitoring is active
macOS File Watcher Options
The default FSEvents observer works well for most projects. If you experience issues, you can switch to an alternative observer via configure_file_watcher:
"auto"(default): Platform default (FSEvents on macOS)"kqueue": Kqueue observer (macOS/BSD)"fsevents": Force FSEvents (macOS only)"polling": Cross-platform polling fallback
Note: Kqueue opens one file descriptor per watched file. For large projects using kqueue, you may need to increase the limit: ulimit -n 10240
Development & Contributing
🔧 Building from Source
git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code-index-mcp🐛 Debugging
npx @modelcontextprotocol/inspector uvx code-index-mcp🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📜 License
🌐 Translations
Available Tools
14 toolsbuild_deep_indexA
Build the deep index (full symbol extraction) for the current project.
This performs a complete re-index and loads it into memory.
Uses parallel processing by default. For large codebases (3000+ files),
tuning max_workers can significantly improve build times.
Args:
max_workers: Maximum number of parallel workers for file processing.
Defaults to min(4, cpu_count) when not specified.
Increase for I/O-bound workloads on machines with many cores.
timeout: Parallel build timeout in seconds. When not specified,
scales dynamically based on file count (0.5s per file,
min 30s, max 600s).
Inputs: max_workers, timeout. Returns: result
check_temp_directoryA
Check the temporary directory used for storing index data.
Inputs: no named parameters. Returns: object
clear_settingsB
Clear all settings and cached data.
Inputs: no named parameters. Returns: result
configure_file_watcherA
Configure file watcher service settings.
Args:
enabled: Whether to enable file watcher
debounce_seconds: Debounce time in seconds before triggering rebuild
additional_exclude_patterns: Additional directory/file patterns to exclude
observer_type: Observer backend to use. Options:
- "auto" (default): platform default observer
- "kqueue": Force kqueue observer (macOS/BSD)
- "fsevents": Force FSEvents observer (macOS only, has known reliability issues)
- "polling": Cross-platform polling fallback (slower but most compatible)
Inputs: enabled, debounce_seconds, additional_exclude_patterns, observer_type. Returns: result
create_temp_directoryA
Create the temporary directory used for storing index data.
Inputs: no named parameters. Returns: object
find_filesA
Find files matching glob pattern using in-memory index. Supports path patterns (.py, test_.js) and filename-only matching (README.md).
Inputs: pattern (required). Returns: result
get_file_summaryB
Get a summary of a specific file, including:
- Line count
- Function/class definitions (for supported languages)
- Import statements
- Basic complexity metrics
Inputs: file_path (required). Returns: object
get_file_watcher_statusA
Get file watcher service status and statistics.
Inputs: no named parameters. Returns: object
get_settings_infoB
Get information about the project settings.
Inputs: no named parameters. Returns: object
get_symbol_bodyA
Get the source code body of a specific symbol (function, method, or class).
This tool retrieves only the code for the specified symbol, enabling efficient
context usage by avoiding loading entire files.
Args:
file_path: Path to the file containing the symbol
symbol_name: Name of the symbol to retrieve (e.g., "process_data", "MyClass.my_method")
Returns:
Dictionary containing:
- status: "success" or "error"
- symbol_name: Name of the symbol
- type: Type of symbol (function, method, class)
- line: Start line number
- end_line: End line number
- code: The actual source code
- signature: Function/method signature (if available)
- docstring: Documentation string (if available)
- called_by: List of symbols that call this symbol
Inputs: file_path (required), symbol_name (required). Returns: object
refresh_indexA
Manually rebuild the project file index. Use after git operations or when index seems stale.
Inputs: no named parameters. Returns: result
refresh_search_toolsA
Manually re-detect the available command-line search tools on the system. This is useful if you have installed a new tool (like ripgrep) after starting the server.
Inputs: no named parameters. Returns: result
search_code_advancedA
Search for code pattern with pagination. Auto-selects best search tool (ugrep/ripgrep/ag/grep). Supports glob file_pattern (e.g., "*.py"), explicit regex mode, and fuzzy matching (ugrep only). Regex matching requires passing regex=True and may require an external search tool.
Inputs: pattern (required), case_sensitive, context_lines, file_pattern, +4 more. Returns: object
set_project_pathC
Set the base project path for indexing.
Inputs: path (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct action: index building, file watching, settings management, searching, etc. Overlap is minimal and descriptions clarify the differences.
All tool names use a consistent verb_noun snake_case pattern (e.g., build_deep_index, check_temp_directory, get_file_summary). No mixing of conventions.
14 tools cover indexing, searching, file details, symbol retrieval, settings, and utilities. This is well-scoped for a code index server, neither sparse nor excessive.
Covers core operations: index build/refresh, file and code search, symbol body retrieval, settings, file watcher. Minor gaps like listing symbols or index statistics exist but do not hinder primary use.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
An MCP server that gives your AI access to the source code and docs of all public github repos
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables LLMs to read, search, and analyze code files with advanced caching and real-time file watching capabilities.640MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).18 npm3Apache 2.0

CodeAlive MCPofficial
AlicenseNot gradedqualityBmaintenanceA Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.91MIT- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) server that enables AI applications to access and analyze local code repositories without manual uploads, providing file listing, content reading, code searching, and project structure analysis capabilities.7MIT