socraticode — Claude Code MCP server: what it does, how to install
Indexes codebases locally, builds dependency graphs, and runs hybrid semantic search via Qdrant.
claude mcp add socraticode -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OLLAMA_API_KEY=<OLLAMA_API_KEY> -e LMSTUDIO_API_KEY=<LMSTUDIO_API_KEY> -e LITELLM_API_KEY=<LITELLM_API_KEY> -e QDRANT_API_KEY=<QDRANT_API_KEY> -- npx -y socraticodeWhat socraticode does
The server parses local repositories to feed deep codebase context directly to AI coding assistants. It combines AST-aware code chunking with hybrid search, fusing BM25 keyword matching and vector embeddings via reciprocal rank fusion. It also computes call flows and symbol-level impact across 18 programming languages.
Local execution relies on Docker to run Qdrant, keeping the index entirely on the local machine without sending code off-device. External embedding providers like OpenAI, Google Gemini, or Ollama can be plugged in when cloud embeddings are needed. Without Docker running locally or explicit remote credentials, the indexing engine cannot start.
A built-in file watcher monitors changes to keep the index fresh across sessions. Checkpoints ensure large indexing jobs resume cleanly after interruptions, while multiple agents can share the same repository index simultaneously.
What it helps with
- locate relevant functions using combined semantic and keyword search
- trace blast radius and symbol dependencies across 18 languages
- visualize module architecture and pinpoint circular dependencies
- index API schemas, database migrations, and infrastructure configurations
Example prompts for the agent
- Find all authentication handlers and map their database dependencies
- Trace the blast radius of modifying calculateBilling across the project
- Check the codebase for circular dependencies between modules
How to install socraticode
Platform CLI
claude mcp add socraticode -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OLLAMA_API_KEY=<OLLAMA_API_KEY> -e LMSTUDIO_API_KEY=<LMSTUDIO_API_KEY> -e LITELLM_API_KEY=<LITELLM_API_KEY> -e QDRANT_API_KEY=<QDRANT_API_KEY> -- npx -y socraticodeReplace <…> with your own values. 12 more environment variables are in the server README
Platform CLI
codex mcp add socraticode --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> --env OPENAI_API_KEY=<OPENAI_API_KEY> --env GOOGLE_API_KEY=<GOOGLE_API_KEY> --env OLLAMA_URL=<OLLAMA_URL> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> -- npx -y socraticodeReplace <…> with your own values. 12 more environment variables are in the server README
Config file
{
"mcpServers": {
"socraticode": {
"command": "npx",
"args": [
"-y",
"socraticode"
],
"env": {
"EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>",
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
"OLLAMA_URL": "<OLLAMA_URL>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>"
}
}
}
}Replace <…> with your own values. 12 more environment variables are in the server README
Config file
{
"servers": {
"socraticode": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"socraticode"
],
"env": {
"EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>",
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
"OLLAMA_URL": "<OLLAMA_URL>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>"
}
}
}
}Replace <…> with your own values. 12 more environment variables are in the server README
Platform CLI
gemini mcp add -e EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OLLAMA_URL=<OLLAMA_URL> -e EMBEDDING_MODEL=<EMBEDDING_MODEL> socraticode npx -y socraticodeReplace <…> with your own values. 12 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about socraticode
How do I install socraticode in Claude Code?
Add the stdio server using `claude mcp add --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> --env OPENAI_API_KEY=<OPENAI_API_KEY> --env GOOGLE_API_KEY=<GOOGLE_API_KEY> --env OLLAMA_URL=<OLLAMA_URL> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --transport stdio socraticode -- npx -y socraticode`.
What does socraticode do?
It provides codebase indexing, hybrid BM25 and vector search, and dependency call-flow graphs for AI assistants.
What are the system requirements for local operation?
The server requires Node.js version 18.17 or higher and Docker to run the local Qdrant instance.
