Github Code Index MCP Server

🚀 Code Index MCP

Code Index MCP is a model context protocol server that enables large language models (LLMs) to index, search, and analyze code in project directories.

✨ Features

• Index and navigate the project file structure.
• Search for specific code patterns.
• Obtain detailed file summaries.
• Analyze code structure and complexity.
• Support multiple programming languages.
• Provide persistent storage for project settings.

📦 Installation

This project uses uv for environment management and dependency installation.

1. Ensure Python 3.10 or a higher version is installed.

2. Install uv (recommended):

   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Get the code:

   # Clone the repository
   git clone https://github.com/your-username/code-index-mcp.git
   

💻 Usage Examples

Basic Usage

# Run the server directly using uv - no additional dependency installation required
uv run run.py

UV will automatically handle all dependency installations based on the project's configuration.

Advanced Usage

Integrate with Claude Desktop

You can easily integrate Code Index MCP into Claude Desktop:

1. Ensure UV is installed (see the Installation section).

2. Locate or create the Claude Desktop configuration file:

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

3. Add the following configuration (replace with actual paths):

   For Windows

   {
     "mcpServers": {
       "code-indexer": {
         "command": "uv",
         "args": [
            "--directory",
            "C:\\Users\\username\\path\\to\\code-index-mcp",
            "run",
            "run.py"
          ]
       }
     }
   }
   

   For macOS/Linux

   {
     "mcpServers": {
       "code-indexer": {
         "command": "uv",
         "args": [
            "--directory",
            "/home/username/path/to/code-index-mcp",
            "run",
            "run.py"
          ]
       }
     }
   }
   

4. Restart Claude Desktop to apply the changes.

General Workflow

1. Set the project path:

   • Use the -p or --path parameter to specify the project root directory.
   • Example: code-indexer --path /your/project/path

2. Search for code:

   • Use the -s or --search parameter to search for code.
   • Example: code-indexer --search "keyword" --path /your/project/path

3. Analyze files:

   • Use the -a or --analyze parameter to analyze specific files.
   • Example: code-indexer --analyze /your/project/path/file.js

4. Navigate the project:

   • Use the -n or --navigate parameter to navigate directories.
   • Example: code-indexer --navigate /your/project/path

🔧 Technical Details

• Persistent storage: The .code_indexer folder is used to store index data and is created in the project root directory by default.
• Dependency management: Use UV for environment and dependency management to ensure all dependencies are correctly installed.
• Supported file types: The following file types are supported:
  • .js, .ts, .py, .java, .cpp, .php
  • .html, .css, .scss, .sass, .less
  • .json, .yaml, .yml, .xml, .ini
  • etc.

⚠️ Important Note

• File path validation prevents directory traversal attacks.
• Absolute path access is not allowed.
• The project path must be explicitly set, with no default value.
• The .code_indexer folder contains a .gitignore file to prevent index data from being committed to version control.

🤝 Contribution

Welcome to add new features or fix bugs through issues or pull requests.

For the Chinese documentation, please refer to README_zh.md.