Weaviate MCP Server

---

🚀 Quick Start

Test the server immediately using the Model Context Protocol (MCP) Inspector, or install and run it directly.

Option 1: Instant Setup with MCP Inspector (Recommended for Testing)

# First, start a local Weaviate instance
docker-compose -f docker-compose.weaviate.yml up -d

# Then test with MCP Inspector
npx @modelcontextprotocol/inspector \
  -e WEAVIATE_URL="localhost" \
  -e WEAVIATE_HTTP_PORT="8080" \
  -e WEAVIATE_GRPC_PORT="50051" \
  -e WEAVIATE_OPENAI_API_KEY="your-openai-api-key" \
  -- \
  uvx --from weaviate-mcp weaviate-mcp

Replace your-openai-api-key with your actual OpenAI API key.

Option 2: Direct Installation & Usage

1. Install the package:

   pip install weaviate-mcp
   

2. Set Environment Variables:

   export WEAVIATE_URL="localhost"
   export WEAVIATE_HTTP_PORT="8080"
   export WEAVIATE_GRPC_PORT="50051"
   export WEAVIATE_OPENAI_API_KEY="your-openai-api-key"
   

3. Run the MCP Server:

   python -m weaviate_mcp
   

Option 3: Using uvx (Run without full installation)

# Ensure WEAVIATE_* environment variables are set as shown above
uvx --from weaviate-mcp weaviate-mcp

📋 Overview

weaviate-mcp is a Python package that enables AI models to interact with Weaviate vector databases through the Model Context Protocol (MCP). It acts as a secure and standardized bridge, allowing AI assistants to leverage Weaviate's powerful vector search and storage capabilities without direct database credential exposure.

What is MCP?

The Model Context Protocol (MCP) provides a standardized interface for AI models to discover and utilize external tools and services. This package implements an MCP server that exposes Weaviate capabilities as discrete, callable "tools."

Key Benefits

• AI-Ready Integration: Purpose-built for AI assistants to naturally interact with vector databases.
• Standardized Protocol: Ensures seamless integration with MCP-compatible AI systems and hubs.
• Enhanced Security: Database credentials remain on the server, isolated from the AI models.
• Comprehensive Vector Operations: Offers semantic search, hybrid search, and full CRUD operations.
• Dynamic Schema Management: Create and manage collections on-the-fly without predefined schemas.
• Robust Error Handling: Provides consistent error patterns for reliable operation.
• Extensive Testing: Underpinned by a comprehensive test suite for correctness and stability.

🏗️ Prerequisites & Setup

Step 1: Weaviate Instance Setup

You need a running Weaviate instance. Choose one of these options:

Option A: Local Development with Docker (Recommended)

1. Download the Docker Compose file:

   curl -O https://raw.githubusercontent.com/your-repo/arclio-mcp-tooling/main/docker-compose.weaviate.yml
   

2. Create environment file:

   cp weaviate-mcp.env.example .env
   # Edit .env and add your OpenAI API key
   

3. Start Weaviate:

   docker-compose -f docker-compose.weaviate.yml up -d
   

4. Verify Weaviate is running:

   curl http://localhost:8080/v1/.well-known/ready
   

Option B: Weaviate Cloud Services (WCS)

1. Sign up at Weaviate Cloud Services
2. Create a new cluster
3. Note your cluster URL and API key
4. Set environment variables accordingly

Step 2: OpenAI API Key

This MCP server uses OpenAI's text embedding models for vectorization:

1. Get your API key from OpenAI Platform
2. Set the WEAVIATE_OPENAI_API_KEY environment variable

⚙️ Configuration

Environment Variables

The MCP server requires the following environment variables:

# Essential connection settings
export WEAVIATE_URL="localhost"                    # Weaviate host (without http/https)
export WEAVIATE_HTTP_PORT="8080"                  # HTTP port
export WEAVIATE_GRPC_PORT="50051"                 # gRPC port (for better performance)

# Required for text vectorization
export WEAVIATE_OPENAI_API_KEY="your-api-key"     # OpenAI API key

# Optional authentication (if your Weaviate instance requires it)
# export WEAVIATE_API_KEY="your-weaviate-api-key"
# export WEAVIATE_USERNAME="username"
# export WEAVIATE_PASSWORD="password"

# Optional performance settings
# export WEAVIATE_TIMEOUT="60"                    # Connection timeout in seconds
# export WEAVIATE_USE_SSL="false"                 # Use SSL/TLS connection

Configuration File

For persistent configuration, create a .env file:

# Copy the example file
cp weaviate-mcp.env.example .env

# Edit with your actual values
nano .env

🛠️ Exposed Capabilities (Tools)

This package exposes comprehensive tools for AI interaction with Weaviate.

Collection Management Tools

• weaviate_create_collection: Create new collections with custom schemas
• weaviate_delete_collection: Delete existing collections
• weaviate_get_schema: Retrieve current database schema

Data Management Tools

• weaviate_insert_object: Insert single objects with duplicate checking
• weaviate_batch_insert_objects: Batch insert multiple objects efficiently
• weaviate_get_object: Retrieve objects by UUID
• weaviate_get_objects: Query multiple objects with filtering and pagination
• weaviate_update_object: Update existing objects
• weaviate_delete_object: Delete objects by UUID

Search & Query Tools

• weaviate_vector_search: Semantic vector search using embeddings
• weaviate_hybrid_search: Combined semantic and keyword search

Analytics & Schema Tools

• weaviate_aggregate: Perform aggregation operations
• weaviate_get_schema_info: Get detailed schema information with statistics
• weaviate_validate_collection_exists: Check if a collection exists
• weaviate_get_collection_stats: Get statistics for a specific collection

🔍 Troubleshooting

Connection Issues

• "Connection refused": Ensure Weaviate is running on the specified host and port

  curl http://localhost:8080/v1/.well-known/ready
  

• "Authentication failed": Check your Weaviate credentials and API keys

• "SSL/TLS errors": Verify WEAVIATE_USE_SSL setting matches your Weaviate configuration

OpenAI Integration Issues

• "Invalid API key": Verify your WEAVIATE_OPENAI_API_KEY is correct and active
• "Rate limit exceeded": OpenAI API has usage limits; check your quota

MCP Server Issues

• "Tool not found": Verify the tool name matches exactly (case-sensitive)
• "Invalid arguments": Check the tool's parameter requirements and types
• "Server not responding": Check server logs for error messages

For detailed debugging, inspect the server's stdout/stderr logs.

📚 Usage Examples

Creating Collections with Vectorization

# Create a collection with OpenAI vectorization for semantic search
await weaviate_create_collection(
    name="Articles",
    description="Collection for storing articles with semantic search",
    properties=[
        {
            "name": "title",
            "data_type": "text",
            "description": "Article title"
        },
        {
            "name": "content",
            "data_type": "text",
            "description": "Article content"
        },
        {
            "name": "author",
            "data_type": "text",
            "description": "Article author"
        }
    ],
    vectorizer_config={
        "type": "text2vec_openai",
        "model": "text-embedding-3-small"
    }
)

Basic CRUD Operations

# Insert an article
result = await weaviate_insert_object(
    collection_name="Articles",
    data={
        "title": "The Future of AI",
        "content": "Artificial intelligence is transforming...",
        "author": "Dr. Jane Smith"
    }
)
object_id = result["object_id"]

# Retrieve the article
article = await weaviate_get_object(
    collection_name="Articles",
    uuid=object_id
)

# Update the article
await weaviate_update_object(
    collection_name="Articles",
    uuid=object_id,
    data={
        "title": "The Future of AI - Updated",
        "content": "Artificial intelligence is rapidly transforming..."
    }
)

Semantic Search (Requires Vectorizer)

# Perform semantic search
results = await weaviate_vector_search(
    collection_name="Articles",
    query_text="machine learning algorithms",
    limit=5
)

# Hybrid search (semantic + keyword)
results = await weaviate_hybrid_search(
    collection_name="Articles",
    query_text="neural networks deep learning",
    alpha=0.7,  # More semantic, less keyword
    limit=10
)

Schema Management

# Get detailed schema information
schema_info = await weaviate_get_schema_info()

# Validate collection exists
validation = await weaviate_validate_collection_exists("Articles")
if validation["exists"]:
    print(f"Collection has {validation['object_count']} objects")

# Compare two collections
comparison = await weaviate_compare_collections("Articles", "Products")
print(f"Common properties: {comparison['common_properties']}")

📝 Contributing

Contributions are welcome! Please refer to the main README.md in the arclio-mcp-tooling monorepo for guidelines on contributing, setting up the development environment, and project-wide commands.

📄 License

This package is licensed under the MIT License. See the LICENSE file in the monorepo root for full details.

🏢 About Arclio

Arclio provides secure and robust Model Context Protocol (MCP) solutions, enabling AI applications to safely and effectively interact with enterprise systems and external services.

---