Which integrations are available for this server?

Allows GitHub Copilot (via VS Code) to perform semantic code search on the indexed codebase using the MCP tools provided by qdrant-codebase-mcp.

How do I use qdrant-codebase-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qdrant-codebase-mcp search for JWT validation logic" 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.

qdrant-codebase-mcp

by theepicsaxguy

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

What it does

qdrant-codebase-mcp runs as a background service that:

Indexes your codebase into a Qdrant vector database using FastEmbed — locally, no external API calls needed
Watches for changes and re-indexes only modified files automatically
Exposes MCP tools so any AI assistant (Roo Code, VS Code Copilot, Claude, Cursor, Windsurf) can search your code by semantic meaning

When an agent calls search_code("where is JWT validation done?") it gets back the right file, the right lines, and a similarity score — not a grep list.

Related MCP server: MCP Codebase Index

How indexing works

File saved
    │
    ▼
chokidar detects write event
    │
    ▼  awaitWriteFinish — waits until the file handle closes
    │
    ▼  per-file debounce (default 2 s)
       resets if the file is saved again before the timer fires
    │
    ▼
IndexingCoordinator.indexFile()
  ├─ delete stale vectors for this file from Qdrant
  ├─ chunk the file  (overlapping windows, 150 lines / 20 overlap)
  ├─ embed all chunks in one batch  (BGE-Small-EN → 384-dim vectors)
  └─ upsert vectors + metadata into Qdrant

Only the changed file is re-indexed on save — not the whole codebase. A full initial index runs once on startup.

What the vectors contain: Each vector point in Qdrant carries the code chunk, file path, language, line numbers, content hash, and timestamp as payload — giving the agent full context alongside the embedding.

Quickstart

You need a running Qdrant instance. The fastest way:

docker run -p 6333:6333 qdrant/qdrant

Then from your project directory:

QDRANT_URL=http://localhost:6333 npx qdrant-codebase-mcp

The server will connect to Qdrant, create a collection, index your code, start watching for changes, and serve MCP over stdio — all in one command.

Install from source with `uvx`

If you want to run directly from GitHub source instead of the published npm package:

QDRANT_URL=http://localhost:6333 \
ROOT_PATH=/path/to/your/project \
uvx --from git+https://github.com/theepicsaxguy/qdrant-codebase-mcp qdrant-codebase-mcp

For Qdrant Cloud or any authenticated endpoint, pass the API key the same way:

QDRANT_URL=https://your-cluster.qdrant.tech \
QDRANT_API_KEY=your-qdrant-api-key \
ROOT_PATH=/path/to/your/project \
uvx --from git+https://github.com/theepicsaxguy/qdrant-codebase-mcp qdrant-codebase-mcp

The uvx launcher clones the Git source, builds the Node server once per commit in a cache directory, and then runs dist/mcp-entry.js with your current environment. node and npm still need to be available on your PATH. If you prefer config files, set CONFIG_PATH=/absolute/path/to/config.yml; environment variables still take precedence over values inside that file.

One-click install into VS Code:

Install in VS Code

MCP client setup

If you have multiple existing Qdrant collections built with different embedding models, configure multiple MCP server entries. Each server process should point at exactly one embedding provider/model combination. Do not mix different embedding spaces inside one server instance.

VS Code (GitHub Copilot / Roo Code)

Add to .vscode/mcp.json in your workspace:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant server URL",
      "default": "http://localhost:6333"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API key (leave empty for local instances)",
      "password": true
    },
    {
      "type": "promptString",
      "id": "embeddingApiKey",
      "description": "Embedding API key for OpenAI-compatible backends",
      "password": true
    }
  ],
  "servers": {
    "qdrant-codebase-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "qdrant-codebase-mcp"],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "ROOT_PATH": "${workspaceFolder}"
      }
    },
    "webdocuments-search": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/theepicsaxguy/qdrant-codebase-mcp",
        "qdrant-codebase-mcp"
      ],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "SERVER_MODE": "search-only",
        "REPO_ID": "webdocuments",
        "COLLECTION_NAME": "webdocuments",
        "EMBEDDING_PROVIDER": "openai-compatible",
        "EMBEDDING_BASE_URL": "https://your-openai-compatible-endpoint/v1",
        "EMBEDDING_API_KEY": "${input:embeddingApiKey}",
        "EMBEDDING_MODEL": "text-embedding-3-large"
      }
    }
  }
}

Use the same pattern to add webdocuments-2, tickets-search, or any other dedicated index. One collection/model pair should map to one MCP server entry.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "qdrant-codebase-mcp": {
      "command": "npx",
      "args": ["-y", "qdrant-codebase-mcp"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "ROOT_PATH": "/path/to/your/project"
      }
    }
  }
}

Claude Code

claude mcp add qdrant-codebase-mcp \
  -e QDRANT_URL=http://localhost:6333 \
  -- npx -y qdrant-codebase-mcp

Cursor

Settings → MCP → Add new MCP server:

{
  "name": "qdrant-codebase-mcp",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "qdrant-codebase-mcp"],
  "env": {
    "QDRANT_URL": "http://localhost:6333",
    "ROOT_PATH": "/path/to/your/project"
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "qdrant-codebase-mcp": {
      "command": "npx",
      "args": ["-y", "qdrant-codebase-mcp"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "ROOT_PATH": "/path/to/your/project"
      }
    }
  }
}

MCP tools

Tool	Input	What it returns
`search_code`	`query`, optional: `repoId`, `language`, `directoryPrefix`, `limit`, `minScore`	Ranked code chunks with file path, line range, language, similarity score
`list_repos`	—	All configured repos with collection name, mode, and root path
`get_repo_status`	`repoId`	Indexing state, timestamps, server mode, embedding provider/model info
`trigger_reindex`	`repoId`	Kicks off a full re-index in the background; unsupported in `search-only`

Example — finding code by concept:

search_code("JWT token validation")

### 1. src/auth/middleware.ts  lines 45–72  ·  repo: my-backend  ·  score: 0.921
\`\`\`typescript
export async function validateJwt(token: string): Promise<JwtPayload> {
  ...
}
\`\`\`

### 2. src/api/guards/auth.guard.ts  lines 12–34  ·  score: 0.887
...

Configuration

All settings are via environment variables or an optional config.yml. Precedence is: environment variables -> config.yml -> built-in defaults.

Variable	Default	Description
`QDRANT_URL`	`http://localhost:6333`	Qdrant server URL
`QDRANT_API_KEY`	—	Qdrant API key (required for Qdrant Cloud)
`SERVER_MODE`	`index-and-watch`	`index-and-watch` or `search-only`
`ROOT_PATH`	`process.cwd()`	Repository root to index (`index-and-watch` only)
`COLLECTION_NAME`	`<folder>-<hash>`	Qdrant collection; required in `search-only`
`REPO_ID`	folder name	Logical name shown in MCP tools
`EMBEDDING_PROVIDER`	`fastembed`	`fastembed` or `openai-compatible`
`EMBEDDING_MODEL`	`fast-bge-small-en-v1.5`	Embedding model name
`EMBEDDING_BASE_URL`	—	OpenAI-compatible embeddings base URL
`EMBEDDING_API_KEY`	—	OpenAI-compatible embeddings API key
`EMBEDDING_DIMENSIONS`	—	Optional explicit embedding vector size
`EMBEDDING_HEADERS_JSON`	—	Optional JSON object of extra embedding headers
`EMBEDDING_BATCH_SIZE`	`64`	Chunks per embedding batch
`CHUNK_MAX_LINES`	`150`	Max lines per code chunk
`CHUNK_OVERLAP_LINES`	`20`	Overlap between adjacent chunks
`MAX_FILE_SIZE_BYTES`	`1000000`	Files larger than this are skipped
`WATCHER_DEBOUNCE_MS`	`2000`	Quiet period after a save before re-indexing
`MIN_SCORE`	`0.78`	Minimum similarity score for search results (0-1)
`PORT`	`3000`	HTTP health/metrics port
`CONFIG_PATH`	—	Path to a `config.yml` for multi-repo setups

Multi-repo config.yml

qdrantUrl: https://your-cluster.qdrant.tech
qdrantApiKey: your-api-key
serverMode: index-and-watch
embeddingProvider: fastembed
embeddingModel: fast-bge-small-en-v1.5
chunkMaxLines: 150
chunkOverlapLines: 20
watcherDebounceMs: 2000

repos:
  - repoId: backend
    rootPath: ./src/backend
    collectionName: backend-code
  - repoId: frontend
    rootPath: ./src/frontend
    collectionName: frontend-code

Dedicated search-only config.yml

Use this mode when the collection already exists in Qdrant and was embedded with an OpenAI-compatible model.

qdrantUrl: https://your-cluster.qdrant.tech
qdrantApiKey: your-api-key
serverMode: search-only
embeddingProvider: openai-compatible
embeddingBaseUrl: https://your-openai-compatible-endpoint/v1
embeddingApiKey: your-embedding-api-key
embeddingModel: text-embedding-3-large

repos:
  - repoId: webdocuments
    collectionName: webdocuments

If you have five dedicated indexes using five different embedding models, run five MCP server entries in your client config. Each entry should set its own REPO_ID, COLLECTION_NAME, EMBEDDING_BASE_URL, and EMBEDDING_MODEL.

Supported embedding models

Model	Dimensions	Notes
`fast-bge-small-en-v1.5`	384	Default — fast, low memory
`fast-bge-base-en-v1.5`	768	Better recall, more memory
`multilingual-e5-large`	1024	Multi-language codebases

HTTP API

The service also exposes a REST API (default port 3000):

Endpoint	Description
`GET /health`	`{"status":"ok"}` when ready
`GET /metrics`	Prometheus metrics
`GET /repos`	List all indexed repos
`GET /repos/:id/status`	Indexing status for a repo
`POST /repos/:id/search`	REST search (same as MCP `search_code`)
`POST /repos/:id/reindex`	Trigger a full re-index

Architecture

npx qdrant-codebase-mcp
         │
         ├── stdio ──────────────────────────────▶ MCP client (AI assistant)
         │          search_code / list_repos /
         │          get_repo_status / trigger_reindex
         │
         └── mcp-entry.ts
                   │
                   ▼
             bootstrap.ts  (initialises all services)
             ┌────────────────────────────────────────────┐
             │                                            │
             │  EmbeddingAdapter                          │
             │  └─ FastEmbed or OpenAI-compatible         │
             │     one provider/model per server process  │
             │                                            │
             │  QdrantAdapter (per repo)                  │
             │  └─ collection lifecycle + upsert/search   │
             │                                            │
             │  IndexingCoordinator                       │
             │  └─ scan → chunk → embed → upsert          │
             │     incremental: only changed files        │
             │                                            │
             │  FileWatcherManager                        │
             │  └─ chokidar + per-file debounce           │
             │     skipped in search-only mode            │
             │                                            │
             │  SearchService                             │
             │  └─ embed query → ANN search → rank        │
             │     single-repo and cross-repo             │
             └────────────────────────────────────────────┘

Development

git clone https://github.com/theepicsaxguy/qdrant-codebase-mcp
cd qdrant-codebase-mcp
npm install
cp config.example.yml config.yml   # fill in your Qdrant URL

npm run typecheck    # tsc --noEmit
npm run lint         # ESLint (zero warnings)
npm test             # unit tests
npm run build        # compile to dist/

Running the MCP server from source

Point your MCP client at the local source instead of the published package. The mcp:dev script uses tsx so changes are reflected without a rebuild.

VS Code — .vscode/mcp.json:

{
  "servers": {
    "qdrant-codebase-mcp-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/qdrant-codebase-mcp/src/mcp-entry.ts"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "ROOT_PATH": "${workspaceFolder}"
      }
    }
  }
}

Claude Code:

claude mcp add qdrant-codebase-mcp-dev \
  -e QDRANT_URL=http://localhost:6333 \
  -e ROOT_PATH=/path/to/your/project \
  -- npx tsx /absolute/path/to/qdrant-codebase-mcp/src/mcp-entry.ts

Any other client (generic stdio):

QDRANT_URL=http://localhost:6333 \
ROOT_PATH=/path/to/your/project \
npx tsx src/mcp-entry.ts

If the source run targets Qdrant Cloud, include QDRANT_API_KEY or point CONFIG_PATH at a config file that contains qdrantApiKey:

QDRANT_URL=https://your-cluster.qdrant.tech \
QDRANT_API_KEY=your-qdrant-api-key \
ROOT_PATH=/path/to/your/project \
npx tsx src/mcp-entry.ts

Source install with `uvx`

For a source install without cloning the repo manually:

uvx --from git+https://github.com/theepicsaxguy/qdrant-codebase-mcp qdrant-codebase-mcp

For authenticated Qdrant instances:

QDRANT_URL=https://your-cluster.qdrant.tech \
QDRANT_API_KEY=your-qdrant-api-key \
ROOT_PATH=/path/to/your/project \
uvx --from git+https://github.com/theepicsaxguy/qdrant-codebase-mcp qdrant-codebase-mcp

If you see authentication failed. Set QDRANT_API_KEY or qdrantApiKey in config., the server started correctly but the Qdrant connection is missing credentials. Pass QDRANT_API_KEY in the client env block or run with CONFIG_PATH=/absolute/path/to/config.yml.

For dedicated external indexes, add environment variables in your client config:

{
  "SERVER_MODE": "search-only",
  "REPO_ID": "webdocuments",
  "COLLECTION_NAME": "webdocuments",
  "EMBEDDING_PROVIDER": "openai-compatible",
  "EMBEDDING_BASE_URL": "https://your-openai-compatible-endpoint/v1",
  "EMBEDDING_API_KEY": "your-embedding-api-key",
  "EMBEDDING_MODEL": "text-embedding-3-large"
}

Security note on `npm audit`

Current installs may report one high-severity advisory in transitive lodash@4.17.23. In this repository that package is pulled in through secretlint, which is only used by the linting toolchain and pre-commit workflow, not by the published server runtime. That still merits dependency hygiene, but it is a much lower risk than a vulnerability in the production dependency graph that handles MCP requests or Qdrant traffic.

See CONTRIBUTING.md for the full contributor guide including commit conventions, changeset requirements, and the release process.

License

MIT

test

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/theepicsaxguy/qdrant-codebase-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server