How to Use a Local Milvus Deployment with Claude Context Instead of Zilliz Cloud

Yes, Claude Context supports fully local Milvus deployments by configuring the MILVUS_ADDRESS environment variable to point to your self-hosted server, requiring no token and no Zilliz Cloud dependency.

The zilliztech/claude-context repository provides flexible vector database adapters that work with any Milvus endpoint, not just Zilliz Cloud. By leveraging the local deployment support built into the core SDK, you can run Claude Context entirely on-premises using a self-hosted Milvus server accessible via gRPC or REST APIs.

Architecture Support for Local Milvus Instances

Claude Context abstracts vector storage behind a VectorDatabase interface, with two Milvus-specific implementations that both support local deployments through explicit address resolution.

MilvusVectorDatabase (gRPC Implementation)

In packages/core/src/vectordb/milvus-vectordb.ts, the MilvusVectorDatabase class implements the VectorDatabase interface using the official Milvus gRPC SDK. The constructor accepts a MilvusConfig object containing an optional address field. The resolveAddress() method (lines 13-20) prioritizes the explicit config.address value; when provided, it bypasses token-based address resolution entirely. For local deployments, simply pass address: "localhost:19530" to establish a direct gRPC connection to your self-hosted server.

MilvusRestfulVectorDatabase (REST Implementation)

For environments where native gRPC bindings cannot load—such as VS Code extensions or Chrome extensions—the MilvusRestfulVectorDatabase class in packages/core/src/vectordb/milvus-restful-vectordb.ts provides an HTTP-based alternative. The resolveAddress() implementation (lines 93-100) follows the same logic as the gRPC version, checking for an explicit address before attempting token resolution. After resolving the address, it constructs a base URL in the format http://<address>/v2/vectordb. Setting address: "localhost:19530" directs the client to the Milvus REST gateway running locally.

Configuration via Environment Variables

The configuration manager reads from environment variables or a global ~/.context/.env file. As documented in docs/getting-started/environment-variables.md, setting MILVUS_ADDRESS without a MILVUS_TOKEN configures Claude Context to connect to a local instance. The VS Code extension mirrors this logic in packages/vscode-extension/src/config/configManager.ts, reading Milvus settings from the IDE's configuration.

Setting Up Local Milvus with Docker

Prerequisites documentation in docs/getting-started/prerequisites.md explicitly includes a "Local Milvus (Advanced)" option with Docker installation instructions.

1. Start Milvus locally using Docker (the simplest method):

docker run -d -p 19530:19530 -p 19121:19121 milvusdb/milvus:latest

2. Export the address or add it to ~/.context/.env:

export MILVUS_ADDRESS=localhost:19530

3. Run Claude Context. The SDK automatically instantiates either MilvusVectorDatabase or MilvusRestfulVectorDatabase using the provided address, with no token required.

Code Example: Switching from Zilliz Cloud to Local Milvus

The repository's basic usage example in examples/basic-usage/index.ts demonstrates how to select the vector database implementation and configure the address. This pattern works identically for local deployments by omitting the token and specifying the local address:

import {
  Context,
  MilvusVectorDatabase,          // gRPC client
  MilvusRestfulVectorDatabase,    // REST client
  AstCodeSplitter,
} from '@zilliz/claude-context-core';
import { envManager } from '@zilliz/claude-context-core';

// Choose the implementation you need (gRPC is the default, REST is safe for VS Code extensions)
const useRestful = false;                     // set true if you need the REST version
const milvusAddress = envManager.get('MILVUS_ADDRESS') ?? 'localhost:19530';

const vectorDb = useRestful
  ? new MilvusRestfulVectorDatabase({ address: milvusAddress })
  : new MilvusVectorDatabase({ address: milvusAddress });

const splitter = new AstCodeSplitter(/* chunkSize */ 2500, /* overlap */ 300);
const ctx = new Context({
  vectorDatabase: vectorDb,
  codeSplitter: splitter,
  supportedExtensions: ['.ts', '.js', '.py'],
});

// Index and search as usual – no other changes needed
await ctx.indexCodebase('/path/to/your/project');
const results = await ctx.semanticSearch('/path/to/your/project', 'search query');

When running locally, the MilvusConfig object receives only the address property, allowing the resolveAddress() method to return your local server endpoint immediately without attempting cloud authentication.

Key Implementation Files

Understanding these source files helps when debugging local connections:

• packages/core/src/vectordb/milvus-vectordb.ts: gRPC-based implementation; contains resolveAddress() logic for direct connections
• packages/core/src/vectordb/milvus-restful-vectordb.ts: REST-based implementation; constructs HTTP URLs from resolved addresses
• packages/vscode-extension/src/config/configManager.ts: VS Code-specific configuration reading
• examples/basic-usage/index.ts: Reference implementation showing implementation selection logic
• docs/getting-started/prerequisites.md: Local deployment instructions and Docker guides
• docs/getting-started/environment-variables.md: Complete MILVUS_ADDRESS and MILVUS_TOKEN documentation

Summary

• Claude Context supports fully local Milvus deployments by configuring the MILVUS_ADDRESS environment variable
• Two implementations exist: MilvusVectorDatabase for gRPC and MilvusRestfulVectorDatabase for HTTP-based connections
• No token is required for local deployments; the resolveAddress() method uses the explicit address when provided
• Docker provides the quickest path to running Milvus locally on localhost:19530
• The architecture in zilliztech/claude-context intentionally abstracts the vector database layer, making Zilliz Cloud optional rather than mandatory

Frequently Asked Questions

Does Claude Context require Zilliz Cloud to function?

No. According to the source code in packages/core/src/vectordb/milvus-vectordb.ts, the SDK only requires a reachable Milvus endpoint. By setting MILVUS_ADDRESS to a local server such as localhost:19530, Claude Context connects directly to your self-hosted instance without any cloud dependency.

Which should I use for a local deployment: gRPC or REST?

Use MilvusVectorDatabase (gRPC) for standalone Node.js applications where native bindings load successfully. Use MilvusRestfulVectorDatabase (REST) for browser extensions or VS Code extensions where gRPC native modules cannot execute. Both support local deployments via the same address configuration parameter.

What port does local Milvus use by default?

The standard Milvus deployment exposes gRPC on port 19530 and the REST API on the same port (or sometimes port 19121 for legacy REST). The Docker run command docker run -p 19530:19530 maps this default port, which you then reference as localhost:19530 in your MILVUS_ADDRESS configuration.

Can I run Claude Context completely offline with local Milvus?

Yes, once the local Milvus server is running and Claude Context is configured with MILVUS_ADDRESS pointing to that local instance, the system operates entirely offline without internet connectivity or Zilliz Cloud authentication. The token parameter in MilvusConfig remains optional for local deployments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}