Weaviate MCP server

Preview — added in v1.37.1

This is a preview feature. The API may change in future releases.

The Weaviate Model Context Protocol (MCP) server is an implementation of the open standard that enables Large Language Models (LLMs) to interact securely with your Weaviate instance.

Instead of pasting context manually, MCP allows compatible clients (like Claude Desktop or IDEs) to directly "see" and interact with your database. Weaviate implements this as a Streamable HTTP server that runs on the same port as the main Weaviate REST API. It exposes tools to inspect schemas, search data (vector/hybrid), and modify objects, governed by Weaviate's authentication and authorization.

---

Using the Weaviate MCP server

The Weaviate MCP server by default runs at http://localhost:8080/v1/mcp if enabled and supports authentication via Bearer tokens (API Keys). To get started:

1. Enable the MCP server (and optionally write access) through environment variables.
2. Ensure your API key has the right permissions if using RBAC.
3. Connect your MCP client using the REST API host and port.

You can also optionally customize tool descriptions to tailor the LLM's understanding of your workflow.

Connect your MCP client

Claude Code

Run the following command in your terminal to add the server (Claude Code MCP docs):

claude mcp add-json weaviate-local '{"type":"http","url":"http://localhost:8080/v1/mcp","headers":{"Authorization":"Bearer YOUR_API_KEY"}}'

If anonymous access is enabled, you can omit the headers field.

Claude Desktop

Claude Desktop does not natively support Streamable HTTP transport. Use mcp-proxy to bridge between Claude Desktop's stdio transport and the Weaviate MCP server.

Config Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "weaviate-local": {
      "command": "mcp-proxy",
      "args": [
        "http://localhost:8080/v1/mcp",
        "--headers",
        "Authorization",
        "Bearer YOUR_API_KEY",
        "--transport",
        "streamablehttp"
      ]
    }
  }
}

Note: Replace YOUR_API_KEY with your actual Weaviate API key. If anonymous access is enabled, you can omit the --headers arguments.

Cursor

Add the following to your .cursor/mcp.json file (Cursor MCP docs). Cursor supports Streamable HTTP connections directly.

{
  "mcpServers": {
    "weaviate-local": {
      "type": "streamable-http",
      "url": "http://localhost:8080/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code

Prerequisites: VS Code 1.102+ with GitHub Copilot enabled (VS Code MCP docs).

Create or edit the mcp.json file in your workspace .vscode folder:

{
  "servers": {
    "weaviate-local": {
      "type": "streamable-http",
      "url": "http://localhost:8080/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Other

Most MCP clients support Streamable HTTP. Use the following connection details:

• URL: http://localhost:8080/v1/mcp
• Transport: Streamable HTTP
• Auth Header: Authorization: Bearer <your-api-key>

Standard JSON configuration format:

{
  "mcpServers": {
    "weaviate-local": {
      "url": "http://localhost:8080/v1/mcp",
      "type": "streamable-http"
    }
  }
}

---

Configuration

The MCP server is built into Weaviate but is disabled by default for security. It is served at the /v1/mcp endpoint on the same port as the REST API (default 8080).

Environment variables

To enable and configure the server, set the following environment variables in your Weaviate configuration (e.g., docker-compose.yml):

Environment Variable	Default	Description
MCP_SERVER_ENABLED	false	Required. Set to true to start the MCP server.
MCP_SERVER_WRITE_ACCESS_ENABLED	false	When true, enables write tools (weaviate-objects-upsert). Default is read-only.
MCP_SERVER_CONFIG_PATH	""	Path to a YAML file for customizing tool descriptions (useful for prompt engineering the LLM's understanding of your specific data). If not provided or file malformed, the default descriptions from the source code will be used.

Permissions

If you use RBAC with fine-grained permissions instead of root access, the role assigned to your API key must include the appropriate MCP permissions. Without them, tool calls are rejected.

Per-tool permissions

Tool	MCP permissions required	Additional collection permissions
weaviate-collections-get-config	read_mcp	read_collections
weaviate-tenants-list	read_mcp	read_data
weaviate-query-hybrid	read_mcp	read_data
weaviate-objects-upsert	create_mcp, update_mcp	create_data, update_data

Custom tool descriptions

You can override the default descriptions provided to the LLM by mounting a YAML or JSON file at MCP_SERVER_CONFIG_PATH.

YAML

# mcp-config.yaml
tools:
  weaviate-query-hybrid:
    description: "Perform a vector or keyword search on a collection."
    arguments:
      query: "The natural language search query to find relevant objects."
      alpha: "0.0 = pure keyword (BM25), 1.0 = pure vector, 0.5 = equal weight (default)."

JSON

{
  "tools": {
    "weaviate-query-hybrid": {
      "description": "Perform a vector or keyword search on a collection.",
      "arguments": {
        "query": "The natural language search query to find relevant objects.",
        "alpha": "0.0 = pure keyword (BM25), 1.0 = pure vector, 0.5 = equal weight (default)."
      }
    }
  }
}

---

Tools

The server exposes different tools depending on your configuration. These are all the available tools:

• weaviate-collections-get-config
• weaviate-tenants-list
• weaviate-query-hybrid
• weaviate-objects-upsert

weaviate-collections-get-config

Retrieves the schema configuration for collections.

Arguments:

• collection_name (string, optional): Specific collection to retrieve. If omitted, returns all.

Returns: JSON object containing class names, properties, and vectorizer settings.

weaviate-tenants-list

Lists tenants for multi-tenant collections.

Arguments:

• collection_name (string, required): The collection to inspect.

Returns: List of tenants and their activity status (HOT/COLD).

weaviate-query-hybrid

Performs a hybrid search combining vector similarity and keyword matching (BM25).

Arguments:

• query (string, required): The natural language search text.
• collection_name (string, required): The collection to search.
• tenant_name (string, optional): Tenant to search within for multi-tenant collections.
• alpha (float, optional): Weighting. 0.0 = pure keyword search, 1.0 = pure vector search. Default is 0.5.
• limit (int, optional): Max results.
• target_vectors (array, optional): Named vectors to use for vector search.
• target_properties (array, optional): Properties to search with BM25. If omitted, searches all text properties.
• return_properties (array, optional): Properties to include in results.
• return_metadata (array, optional): Metadata fields to return (e.g., id, distance, score, creationTimeUnix).

Returns: Ranked objects with similarity scores and distances.

weaviate-objects-upsert

MCP write access

This tool is only available if MCP_SERVER_WRITE_ACCESS_ENABLED=true.

Batch inserts or updates objects.

Arguments:

• collection_name (string, required): The collection to upsert into.
• tenant_name (string, optional): Tenant for multi-tenant collections.
• objects (array, required): List of objects containing properties and optional uuid or vectors.

Returns: Array of results containing UUIDs or error messages per object.

---

Further resources

• Vibe coding - Best practices
• Weaviate Docs MCP server

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.