Weaviate Docs MCP Server

MCP server for searching Weaviate documentation using semantic search.

Setup

1. Clone the Weaviate docs repository:

git clone https://github.com/weaviate/docs.git

2. Install dependencies:

uv sync

3. Create .env file:

cp .env.example .env

Edit .env with your credentials:

• WEAVIATE_DOCS_MCP_URL: Your Weaviate cluster URL
• WEAVIATE_DOCS_MCP_API_KEY: Your Weaviate API key
• COHERE_API_KEY: Your Cohere API key (for embeddings)
• CATALOG_COLLECTION_NAME: Collection name (default: DocCatalog)
• DOCS_ROOT_PATH: Base path to the docs folder (default: ./docs/docs)
• DOCS_PATHS: (Optional) Comma-separated subdirectories to scan (default: weaviate,deploy)

Usage

With Claude Desktop

Add to your Claude Desktop config:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "weaviate-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jphwang/code/weaviate-docs-mcp",
        "run",
        "weaviate-docs-mcp"
      ]
    }
  }
}

Available Tools

search_docs

Search documentation by semantic similarity.

Parameters:

• query (string, required): Search query to find relevant documentation
• return_type (string, optional): Format of results (default: "full_documents")

Returns: Up to 5 most relevant documents with full content and referenced code files

Catalog Management

The catalog must be updated manually before the MCP server can search documents.

Update the catalog

Run the standalone script to scan for new/modified documents:

python update_catalog.py

Or limit the number of documents (useful for testing):

python update_catalog.py --limit 5

This script:

• Scans the docs directory for new or modified markdown files
• Generates metadata (title, topics, summary, doctype) using AI
• Stores metadata in both local catalog.json and Weaviate
• Removes entries for deleted documents
• Syncs local catalog with Weaviate: Re-adds any documents that exist in the local catalog but are missing from Weaviate

The script intelligently handles three scenarios:

1. New or modified documents: Generates fresh metadata and updates both catalog and Weaviate
2. Deleted documents: Removes from both local catalog and Weaviate
3. Out-of-sync documents: Re-syncs documents that exist in local catalog but missing from Weaviate (e.g., after Weaviate collection recreation)

Architecture

This MCP server is designed for read-only documentation search. Catalog management is intentionally kept separate as an admin operation.

Components

• MCP Server (src/weaviate_docs_mcp/server.py) - Provides search_docs tool for clients
• Catalog Script (update_catalog.py) - Admin tool to rebuild the search index
• Document Loader - Parses markdown files and extracts referenced code
• Database Layer - Connects to Weaviate for vector search

Why separate catalog updates?

Catalog updates are expensive operations that:

• Process potentially thousands of documents
• Use AI credits for metadata generation
• Take significant time (minutes to hours)
• Should be controlled by administrators

By keeping this separate, the MCP server remains fast and focused on search.

Development

Run the server:

uv run weaviate-docs-mcp