Tea Rags MCP Server

How to use

You will run Tea Rags MCP either as a local (stdio) server or as a remote HTTP server, and connect a client that speaks MCP to index code, run semantic searches, and manage collections.

How to install

Prerequisites you need before installing: Node.js 22 or newer, and Podman or Docker with Compose support for the quick start.

# Clone the project
git clone https://github.com/mhalder/qdrant-mcp-server.git
cd qdrant-mcp-server

# Install dependencies
npm install

# Start services (choose one)
podman compose up -d   # Using Podman
docker compose up -d   # Using Docker

# Pull the embedding model
podman exec ollama ollama pull nomic-embed-text  # Podman
# or
docker exec ollama ollama pull nomic-embed-text  # Docker

# Build the project
npm run build

Configuration and usage notes

You can run Tea Rags MCP as a local stdio server or expose it via HTTP for remote clients. The server provides a HTTP endpoint at /mcp when run in HTTP mode, and you can configure clients to connect to that endpoint.

Start the HTTP transport server (example) with environment variables and the Node runtime, then connect your MCP client to the given URL.

TRANSPORT_MODE=http HTTP_PORT=3000 node build/index.js
```

Configure a client to connect to the MCP server:
```
{
  "mcpServers": {
    "tea_rags": {
      "url": "http://your-server:3000/mcp"
    }
  }
}

Additional important sections

Features cover zero setup with local embedding, privacy-first local vector storage, and code-aware indexing. You can choose among providers (Ollama, OpenAI, Cohere, Voyage AI) and tune performance with extensive environment variables.

Prompts configuration lets you create guided workflows without code changes. Prompts default to prompts.json in the project root, but you can point to a custom file with PROMPTS_CONFIG_FILE.

Tools

Tea Rags MCP exposes a comprehensive set of tools to manage collections, documents, and code indexing. These tools enable you to create and manage data, perform semantic searches, and index codebases.

Troubleshooting

If you encounter issues, verify the deployment setup and container status, confirm the Qdrant and Ollama services are running, and check access permissions and API keys. Common problems include transport misconfigurations, missing collections, or API key errors.

Performance tips

Tune batching, concurrency, and IO settings to match your hardware. For remote servers, increase batch sizes and parallelism carefully. For local development on laptops, reduce batch sizes and concurrency to fit memory.

Development and testing notes

Development and testing workflows rely on npm scripts for building and testing. Tests include unit tests and real integration tests that validate embedding, Qdrant operations, and metadata integration.

FAQ and quick references

For quick setup, ensure you run the HTTP transport server to expose the MCP endpoint and then configure your MCP client to point to the /mcp path on that server.

create_collection

Create a collection with a specified distance metric (Cosine, Euclid, Dot)

list_collections

List all existing collections

get_collection_info

Retrieve details and statistics for a collection

delete_collection

Delete a collection and all its documents

add_documents

Add documents with automatic embedding and optional metadata

semantic_search

Perform natural language search with optional metadata filtering

hybrid_search

Perform hybrid search combining semantic and keyword search with RRF

delete_documents

Delete documents by their IDs

index_codebase

Index a codebase for semantic code search using AST-aware chunking

search_code

Search indexed codebase using natural language queries

reindex_changes

Incrementally re-index only changed files

get_index_status

Get indexing status and statistics for a codebase

clear_index

Delete all indexed data for a codebase