Litellm Vector Store MCP

LiteLLM矢量存储MCP服务器

生产准备就绪 模型上下文协议（MCP） 服务器，使Claude能够在LiteLLM向量存储中语义搜索相关代码、文档和配置文件。

✨ 特性

• 🔍 语义搜索：使用自然语言查询搜索整个代码库
• 📚 多矢量存储：动态搜索7+不同的框架代码库
• 🔄 自动发现：从LiteLLM API自动列出可用的矢量存储
• 📊 多种格式：获取Markdown（人类可读）或JSON（程序化）格式的结果
• 📄 完整引用：每个结果的文件路径、相关性得分和内容片段
• 🔒 安全：环境变量扩展，配置中没有明文API密钥
• 🐳 Docker就绪：生产级集装箱化，便于部署
• 🚀 符合MCP标准：遵循FastMCP的所有官方MCP最佳实践
• 💬 Claude代码集成：本机CLI命令和.mcp.json支持
• ⚡ 异步I/O：使用httpx进行非阻塞HTTP请求
• ✅ 输入验证：Pydantic V2型号确保型号安全
• 🎯 可操作错误：清晰、有用的错误消息，指导您找到解决方案

🚀 快速开始

5分钟后开始跑步： 看 QUICKSTART.md 获取完整的设置指南。

🐳 Docker镜像

GCP工件注册表中提供了预构建的多平台映像：

us-central1-docker.pkg.dev/ngfw-coe/litellm-vector-store-mcp/litellm-vector-store-mcp:latest

支持的平台：

• ✅ linux/amd64 -英特尔/AMD处理器（Windows WSL、Linux、英特尔Mac）
• ✅ linux/arm64 -ARM处理器（苹果Silicon Mac、ARM服务器）

无需构建！ Docker会自动为您的系统提取正确的架构。

一个命令设置（安全方法）

# 1. Configure Docker for GCP and pull image
gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
docker pull us-central1-docker.pkg.dev/ngfw-coe/litellm-vector-store-mcp/litellm-vector-store-mcp:latest

# 2. Add credentials to shell (SECURE - not in config files)
cat >> ~/.zshrc << 'EOF'
export LITELLM_API_KEY=sk-your-api-key
export LITELLM_VECTOR_STORE_ID=2341871806232657920
EOF
source ~/.zshrc

# 3. Add MCP server with environment variable expansion
claude mcp add-json --scope user litellm-vector-store '{
  "type": "stdio",
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "LITELLM_API_KEY=${LITELLM_API_KEY}",
    "-e", "LITELLM_VECTOR_STORE_ID=${LITELLM_VECTOR_STORE_ID:-2341871806232657920}",
    "-e", "LITELLM_BASE_URL=${LITELLM_BASE_URL:-https://litellm.psolabs.com}",
    "us-central1-docker.pkg.dev/ngfw-coe/litellm-vector-store-mcp/litellm-vector-store-mcp:latest"
  ]
}'

# 4. Restart Claude Code completely (Cmd+Q, then reopen)

🔒 安全： 外壳环境中的API密钥，配置使用 ${LITELLM_API_KEY} （无明文）。

验证设置

# Check server is loaded
claude mcp list

# Should show: litellm-vector-store (stdio) - user scope

与克劳德一起测试

问克劳德：

What vector stores are available?

应该列出你的所有7个矢量库！

______________________________________________________________________

📚 文档

用户指南

开发者指南

______________________________________________________________________

🎯 可用工具

litellm_list_vector_stores

发现LiteLLM实例中所有可用的矢量存储。

参数：

• response_format （字符串，可选）：输出格式-“markdown”或“json”（默认：“markdown）

克劳德用法示例：

What vector stores are available?

退货： 包含ID、名称和描述的7+矢量存储列表。

______________________________________________________________________

litellm_search_vector_store

使用带有完整引用的自然语言查询搜索向量存储。

参数：

• query （字符串，必填）：自然语言搜索查询（2-500个字符）
• max_results （整数，可选）：要返回的结果数（1-20，默认值：5）
• response_format （字符串，可选）：输出格式-“markdown”或“json”（默认：“markdown）
• vector_store （字符串，可选）：要搜索的矢量存储名称或ID（默认值：使用LITELL_Vector_store_ID）

例子：

{
  "query": "How is authentication implemented?",
  "max_results": 10,
  "response_format": "markdown",
  "vector_store": "panser-corpus"
}

克劳德用法示例：

Search panser-corpus for authentication code
Find Redis configuration in internal-corpus
Compare Docker setups across all frameworks

退货：

Markdown格式（默认）：

# Vector Store Search Results

**Query:** How is the GKE cluster configured?
**Results Found:** 5

## Result 1: main.tf.txt
- **Relevance Score:** 0.3948
- **File Path:** `gs://...`
### Content:
[Terraform code...]

JSON格式：

{
  "query": "How is the GKE cluster configured?",
  "total_results": 5,
  "truncated": false,
  "results": [
    {
      "score": 0.3948,
      "filename": "main.tf.txt",
      "file_id": "gs://...",
      "content": "...",
      "attributes": {}
    }
  ]
}

______________________________________________________________________

🐳 Docker部署

构建与运行

# Build image
docker build -t litellm-vector-store-mcp:latest .

# Run with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

分布

推送到Docker Hub以便于共享：

docker tag litellm-vector-store-mcp:latest yourusername/litellm-vector-store-mcp:latest
docker push yourusername/litellm-vector-store-mcp:latest

其他人可以拉动并使用：

docker pull yourusername/litellm-vector-store-mcp:latest

看 **** 完整的Docker指南。

______________________________________________________________________

🔧 配置

环境变量

注： 有关gcloud代理设置，请参阅 QUICKSTART.md中的高级配置

测试配置

python test_config.py

预期产量：

✓ SUCCESS! Vector store is accessible
  Found 10 results for test query

______________________________________________________________________

🎓 MCP最佳实践

此服务器遵循所有官方MCP最佳实践：

✅ FastMCP框架：根据类型提示自动生成架构 ✅ Pydantic V2验证：类型安全输入验证 ✅ 工具注释: readOnlyHint, destructiveHint, idempotentHint, openWorldHint ✅ 响应格式：支持JSON和Markdown ✅ 字符限制：25000个字符限制，智能截断 ✅ 可操作错误：引导用户找到解决方案的明确信息 ✅ 异步I/O：使用httpx进行非阻塞HTTP请求 ✅ 类型提示：全面覆盖所有类型 ✅ 综合文档：所有函数的详细文档字符串

看 改进_总结.md 了解完整细节。

______________________________________________________________________

📖 用法示例

基本搜索

问克劳德：

Search the vector store for how Redis is configured

克劳德将：

1. 呼叫 litellm_search_vector_store with query=“Redis是如何配置的”
2. 接收包含文件路径和内容的结果
3. 解释和说明配置

高级搜索

问克劳德：

Find all Terraform modules related to GKE, return 10 results in JSON format

克劳德将：

1. 调用该工具 max_results=10 和 response_format="json"
2. 接收结构化JSON数据
3. 处理并呈现调查结果

后续问题

Based on those results, how does the GKE module differ from the bastion module?

克劳德将：

1. 搜索这两个模块
2. 比较实现
3. 解释主要差异

看 用法_示例.md 更多示例。

______________________________________________________________________

🔐 安全

看 安全.md 完整的安全指南。

推荐设置（安全）

✅ 使用环境变量扩展 -外壳环境中的API密钥，而不是配置文件：

# In ~/.zshrc
export LITELLM_API_KEY=sk-your-key
export LITELLM_VECTOR_STORE_ID=2341871806232657920

# In MCP config
"-e", "LITELLM_API_KEY=${LITELLM_API_KEY}"  // References env var, not plaintext

最佳实践

• ✅ 环境变量：使用 ${VAR} 配置中的扩展（无明文密钥）
• ✅ 外壳环境：将凭据存储在 ~/.zshrc 或单独文件
• ✅ 非根容器：运行方式 mcp 用户（UID 1000）
• ✅ 输入验证：Pydantic验证所有用户输入
• ✅ 启动验证：启动前检查API密钥是否存在
• ✅ 需要重新启动：添加env变量后，Claude代码必须重新启动

安全级别

看 安全.md 了解每种方法的详细实现。

______________________________________________________________________

🛠️ 故障排除

身份验证失败错误

错误： "Error: Authentication failed. Please check your LITELLM_API_KEY..."

原因： Claude Code会话中未加载环境变量

解决方案：

# 1. Verify env vars are in ~/.zshrc
tail -5 ~/.zshrc  # Should show export LITELLM_API_KEY=...

# 2. COMPLETELY RESTART Claude Code (Cmd+Q, then reopen)
# Environment variables are only loaded when Claude Code starts

# 3. Verify in new terminal
echo $LITELLM_API_KEY | head -c 10  # Should show: sk-a8d9e2b

服务器无法启动

# Check environment variables
python test_config.py

# Test Docker manually
docker run -i --rm -e LITELLM_API_KEY=$LITELLM_API_KEY \
  -e LITELLM_VECTOR_STORE_ID=$LITELLM_VECTOR_STORE_ID \
  litellm-vector-store-mcp:latest

克劳德看不见工具

1. 使用以下方式验证配置： claude mcp list
2. 检查中的JSON语法 .mcp.json 或 ~/.claude.json
3. 使用绝对路径（非相对路径）
4. 完全重新启动Claude代码 （Cmd+Q）

搜索未返回任何结果

1. 使用 litellm_list_vector_stores 查看可用商店
2. 验证矢量存储ID或名称是否正确
3. 尝试更广泛的搜索词
4. 检查API键是否有权访问特定的矢量存储

看 CLAUDE_CODE_SETUP.md 和 安全.md 获取完整指南。

______________________________________________________________________

🤝 贡献

欢迎投稿！此服务器如下：

• MCP最佳实践：所有官方指南
• 类型安全：Pydantic模型+类型提示
• 文档：全面的文档字符串
• 测试：验证 test_config.py

______________________________________________________________________

📜 许可证

MIT许可证-随意修改和分发

______________________________________________________________________

🔗 资源

• MCP协议文件
• LiteLLM文档
• FastMCP框架
• Pydantic文档

______________________________________________________________________

🚀 快速参考

Docker命令

# Configure Docker for GCP
gcloud auth configure-docker us-central1-docker.pkg.dev --quiet

# Pull image from Artifact Registry
docker pull us-central1-docker.pkg.dev/ngfw-coe/litellm-vector-store-mcp/litellm-vector-store-mcp:latest

# Run
docker run --rm -i \
  -e LITELLM_API_KEY=$LITELLM_API_KEY \
  -e LITELLM_VECTOR_STORE_ID=$LITELLM_VECTOR_STORE_ID \
  us-central1-docker.pkg.dev/ngfw-coe/litellm-vector-store-mcp/litellm-vector-store-mcp:latest

# Build locally (only if modifying)
docker build -t us-central1-docker.pkg.dev/ngfw-coe/litellm-vector-store-mcp/litellm-vector-store-mcp:latest .
docker push us-central1-docker.pkg.dev/ngfw-coe/litellm-vector-store-mcp/litellm-vector-store-mcp:latest

Python命令

# Install
pip install -r requirements.txt

# Test
python test_config.py

# Run
python server.py

克劳德集成

# Edit config
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart Claude
killall Claude && open -a Claude

______________________________________________________________________

📈 状态

• ✅ 符合MCP协议
• ✅ 生产就绪
• ✅ Docker容器化
• ✅ 完整记录
• ✅ 类型安全
• ✅ 安全强化

已准备好部署和分发！ 🎉