light weight MCP for code that just works A super light-weight, effective embedded MCP (AST-based) that understand and searches your codebase that just works! Using CocoIndex - an Rust-based ultra performant data transformation engine. No blackbox. Works for Claude, Codex, Cursor - any coding agent. - Instant token saving by 70%. - 1 min setup - Just claude/codex mcp add works! Please help star
Add this skill
npx mdskills install cocoindex-io/cocoindex-codeComprehensive semantic code search MCP with AST-based indexing, strong multi-language support, and excellent setup docs
1<p align="center">2<img width="2428" alt="cocoindex code" src="https://github.com/user-attachments/assets/d05961b4-0b7b-42ea-834a-59c3c01717ca" />3</p>456<h1 align="center">light weight MCP for code that just works </h1>78910111213A super light-weight, effective embedded MCP **(AST-based)** that understand and searches your codebase that just works! Using [CocoIndex](https://github.com/cocoindex-io/cocoindex) - an Rust-based ultra performant data transformation engine. No blackbox. Works for Claude, Codex, Cursor - any coding agent.1415- Instant token saving by 70%.16- **1 min setup** - Just claude/codex mcp add works!1718<div align="center">1920[](https://discord.com/invite/zpA9S2DR7s)21[](https://github.com/cocoindex-io/cocoindex)22[](https://cocoindex.io/docs/getting_started/quickstart)23[](https://opensource.org/licenses/Apache-2.0)24<!--[](https://pypistats.org/packages/cocoindex) -->25[](https://pepy.tech/projects/cocoindex)26[](https://github.com/cocoindex-io/cocoindex/actions/workflows/CI.yml)27[](https://github.com/cocoindex-io/cocoindex/actions/workflows/release.yml)282930🌟 Please help star [CocoIndex](https://github.com/cocoindex-io/cocoindex) if you like this project!3132[Deutsch](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=de) |33[English](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=en) |34[Español](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=es) |35[français](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=fr) |36[日本語](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ja) |37[한국어](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ko) |38[Português](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=pt) |39[Русский](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ru) |40[中文](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=zh)4142</div>434445## Get Started - zero config, let's go!!4647Using [pipx](https://pipx.pypa.io/stable/installation/):48```bash49pipx install cocoindex-code # first install50pipx upgrade cocoindex-code # upgrade51```5253Using [uv](https://docs.astral.sh/uv/getting-started/installation/):54```bash55uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"56```5758### Claude59```bash60claude mcp add cocoindex-code -- cocoindex-code61```6263### Codex64```bash65codex mcp add cocoindex-code -- cocoindex-code66```6768### OpenCode69```bash70opencode mcp add71```72Enter MCP server name: `cocoindex-code`73Select MCP server type: `local`74Enter command to run: `cocoindex-code`7576Or use opencode.json:77```78{79 "$schema": "https://opencode.ai/config.json",80 "mcp": {81 "cocoindex-code": {82 "type": "local",83 "command": [84 "cocoindex-code"85 ]86 }87 }88}89```9091### Build the Index9293For large codebases, we recommend running the indexer once before using the MCP so you can see the progress:9495```bash96cocoindex-code index97```9899This lets you monitor the indexing process and ensure everything is ready. After the initial build, the MCP server will automatically keep the index up-to-date in the background as files change.100101> For small projects you can skip this step — the MCP server will build the index automatically on first use.102103## When Is the MCP Triggered?104105Once configured, your coding agent (Claude Code, Codex, Cursor, etc.) automatically decides when semantic code search is helpful — especially for finding code by description, exploring unfamiliar codebases, fuzzy/conceptual matches, or locating implementations without knowing exact names.106107You can also nudge the agent explicitly, e.g. *"Use the cocoindex-code MCP to find how user sessions are managed."* For persistent instructions, add guidance to your project's `AGENTS.md` or `CLAUDE.md`:108109```110Use the cocoindex-code MCP server for semantic code search when:111- Searching for code by meaning or description rather than exact text112- Exploring unfamiliar parts of the codebase113- Looking for implementations without knowing exact names114- Finding similar code patterns or related functionality115```116117## Features118- **Semantic Code Search**: Find relevant code using natural language queries when grep doesn't work well, and save tokens immediately.119- **Ultra Performant to code changes**:⚡ Built on top of ultra performant [Rust indexing engine](https://github.com/cocoindex-io/cocoindex/edit/main/README.md). Only re-indexes changed files for fast updates.120- **Multi-Language Support**: Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, Shell121- **Embedded**: Portable and just works, no database setup required!122- **Flexible Embeddings**: By default, no API key required with Local SentenceTransformers - totally free! You can customize 100+ cloud providers.123124125## Configuration126127| Variable | Description | Default |128|----------|-------------|---------|129| `COCOINDEX_CODE_ROOT_PATH` | Root path of the codebase | Auto-discovered (see below) |130| `COCOINDEX_CODE_EMBEDDING_MODEL` | Embedding model (see below) | `sbert/sentence-transformers/all-MiniLM-L6-v2` |131| `COCOINDEX_CODE_BATCH_SIZE` | Max batch size for local embedding model | `16` |132| `COCOINDEX_CODE_EXTRA_EXTENSIONS` | Additional file extensions to index (comma-separated, e.g. `"inc:php,yaml,toml"` — use `ext:lang` to override language detection) | _(none)_ |133134135### Root Path Discovery136137If `COCOINDEX_CODE_ROOT_PATH` is not set, the codebase root is discovered by:1381391. Finding the nearest parent directory containing `.cocoindex_code/`1402. Finding the nearest parent directory containing `.git/`1413. Falling back to the current working directory142143### Embedding model144By default - this project use a local SentenceTransformers model (`sentence-transformers/all-MiniLM-L6-v2`). No API key required and completely free!145146Use a code specific embedding model can achieve better semantic understanding for your results, this project supports all models on Ollama and 100+ cloud providers.147148Set `COCOINDEX_CODE_EMBEDDING_MODEL` to any [LiteLLM-supported model](https://docs.litellm.ai/docs/embedding/supported_embedding), along with the provider's API key:149150<details>151<summary>Ollama (Local)</summary>152153```bash154claude mcp add cocoindex-code \155 -e COCOINDEX_CODE_EMBEDDING_MODEL=ollama/nomic-embed-text \156 -- cocoindex-code157```158159Set `OLLAMA_API_BASE` if your Ollama server is not at `http://localhost:11434`.160161</details>162163<details>164<summary>OpenAI</summary>165166```bash167claude mcp add cocoindex-code \168 -e COCOINDEX_CODE_EMBEDDING_MODEL=text-embedding-3-small \169 -e OPENAI_API_KEY=your-api-key \170 -- cocoindex-code171```172173</details>174175<details>176<summary>Azure OpenAI</summary>177178```bash179claude mcp add cocoindex-code \180 -e COCOINDEX_CODE_EMBEDDING_MODEL=azure/your-deployment-name \181 -e AZURE_API_KEY=your-api-key \182 -e AZURE_API_BASE=https://your-resource.openai.azure.com \183 -e AZURE_API_VERSION=2024-06-01 \184 -- cocoindex-code185```186187</details>188189<details>190<summary>Gemini</summary>191192```bash193claude mcp add cocoindex-code \194 -e COCOINDEX_CODE_EMBEDDING_MODEL=gemini/text-embedding-004 \195 -e GEMINI_API_KEY=your-api-key \196 -- cocoindex-code197```198199</details>200201<details>202<summary>Mistral</summary>203204```bash205claude mcp add cocoindex-code \206 -e COCOINDEX_CODE_EMBEDDING_MODEL=mistral/mistral-embed \207 -e MISTRAL_API_KEY=your-api-key \208 -- cocoindex-code209```210211</details>212213<details>214<summary>Voyage (Code-Optimized)</summary>215216```bash217claude mcp add cocoindex-code \218 -e COCOINDEX_CODE_EMBEDDING_MODEL=voyage/voyage-code-3 \219 -e VOYAGE_API_KEY=your-api-key \220 -- cocoindex-code221```222223</details>224225<details>226<summary>Cohere</summary>227228```bash229claude mcp add cocoindex-code \230 -e COCOINDEX_CODE_EMBEDDING_MODEL=cohere/embed-english-v3.0 \231 -e COHERE_API_KEY=your-api-key \232 -- cocoindex-code233```234235</details>236237<details>238<summary>AWS Bedrock</summary>239240```bash241claude mcp add cocoindex-code \242 -e COCOINDEX_CODE_EMBEDDING_MODEL=bedrock/amazon.titan-embed-text-v2:0 \243 -e AWS_ACCESS_KEY_ID=your-access-key \244 -e AWS_SECRET_ACCESS_KEY=your-secret-key \245 -e AWS_REGION_NAME=us-east-1 \246 -- cocoindex-code247```248249</details>250251<details>252<summary>Nebius</summary>253254```bash255claude mcp add cocoindex-code \256 -e COCOINDEX_CODE_EMBEDDING_MODEL=nebius/BAAI/bge-en-icl \257 -e NEBIUS_API_KEY=your-api-key \258 -- cocoindex-code259```260261</details>262263Any model supported by LiteLLM works — see the [full list of embedding providers](https://docs.litellm.ai/docs/embedding/supported_embedding).264265### GPU-optimised local model266267If you have a GPU, [`nomic-ai/CodeRankEmbed`](https://huggingface.co/nomic-ai/CodeRankEmbed) delivers significantly better code retrieval than the default model. It is 137M parameters, requires ~1 GB VRAM, and has an 8192-token context window.268269```bash270claude mcp add cocoindex-code \271 -e COCOINDEX_CODE_EMBEDDING_MODEL=sbert/nomic-ai/CodeRankEmbed \272 -e COCOINDEX_CODE_BATCH_SIZE=16 \273 -- cocoindex-code274```275276> **Note:** Switching models requires re-indexing your codebase (the vector dimensions differ).277278## MCP Tools279280### `search`281282Search the codebase using semantic similarity.283284```285search(286 query: str, # Natural language query or code snippet287 limit: int = 10, # Maximum results (1-100)288 offset: int = 0, # Pagination offset289 refresh_index: bool = True # Refresh index before querying290)291```292293The `refresh_index` parameter controls whether the index is refreshed before searching:294295- `True` (default): Refreshes the index to include any recent changes296- `False`: Skip refresh for faster consecutive queries297298Returns matching code chunks with:299300- File path301- Language302- Code content303- Line numbers (start/end)304- Similarity score305306307## Supported Languages308309| Language | Aliases | File Extensions |310|----------|---------|-----------------|311| c | | `.c` |312| cpp | c++ | `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp` |313| csharp | csharp, cs | `.cs` |314| css | | `.css`, `.scss` |315| dtd | | `.dtd` |316| fortran | f, f90, f95, f03 | `.f`, `.f90`, `.f95`, `.f03` |317| go | golang | `.go` |318| html | | `.html`, `.htm` |319| java | | `.java` |320| javascript | js | `.js` |321| json | | `.json` |322| kotlin | | `.kt`, `.kts` |323| markdown | md | `.md`, `.mdx` |324| pascal | pas, dpr, delphi | `.pas`, `.dpr` |325| php | | `.php` |326| python | | `.py` |327| r | | `.r` |328| ruby | | `.rb` |329| rust | rs | `.rs` |330| scala | | `.scala` |331| solidity | | `.sol` |332| sql | | `.sql` |333| swift | | `.swift` |334| toml | | `.toml` |335| tsx | | `.tsx` |336| typescript | ts | `.ts` |337| xml | | `.xml` |338| yaml | | `.yaml`, `.yml` |339340Common generated directories are automatically excluded:341342- `__pycache__/`343- `node_modules/`344- `target/`345- `dist/`346- `vendor/` (Go vendored dependencies, matched by domain-based child paths)347348## Troubleshooting349350### `sqlite3.Connection object has no attribute enable_load_extension`351352Some Python installations (e.g. the one pre-installed on macOS) ship with a SQLite library that doesn't enable extensions.353354**macOS fix:** Install Python through [Homebrew](https://brew.sh/):355356```bash357brew install python3358```359360Then re-install cocoindex-code (see [Get Started](#get-started---zero-config-lets-go) for install options):361362Using pipx:363```bash364pipx install cocoindex-code # first install365pipx upgrade cocoindex-code # upgrade366```367368Using uv (install or upgrade):369```bash370uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"371```372373## Large codebase / Enterprise374[CocoIndex](https://github.com/cocoindex-io/cocoindex) is an ultra effecient indexing engine that also works on large codebase at scale on XXX G for enterprises. In enterprise scenarios it is a lot more effecient to do index share with teammates when there are large repo or many repos. We also have advanced features like branch dedupe etc designed for enterprise users.375376If you need help with remote setup, please email our maintainer linghua@cocoindex.io, happy to help!!377378## License379380Apache-2.0381
Full transparency — inspect the skill content before installing.