使用说明

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个矢量库！

📚 文档

用户指南

指南	目的
QUICKSTART.md ⭐	从这里开始 -使用安全配置进行5分钟的Claude代码设置
安全.md 🔒	安全的API密钥管理和最佳实践
用法_示例.md	Claude如何解读搜索结果
CLAUDE_CODE_SETUP.md	详细的Claude桌面/代码集成指南
DOCKER_DEPLOYMENT.md	Docker部署和分发

开发者指南

指南	目的
改进_总结.md	应用了所有MCP最佳实践
docs/MULTI_STORE_USAGE.md	多矢量存储的使用和示例
docs/	技术文档和架构
`test_config.py`	配置验证器
`test_multi_store.py`	多店铺功能测试

🎯 可用工具

`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_DEPLOYMENT.md 完整的Docker指南。

🔧 配置

环境变量

变量	必填	默认	描述
`LITELLM_API_KEY`	✅ 是	-	您的LiteLLM API密钥
`LITELLM_VECTOR_STORE_ID`	✅ 是	-	要搜索的矢量存储ID
`LITELLM_BASE_URL`	没有	`https://litellm.psolabs.com`	litellm服务器URL 或使用： `http://localhost:5600` （gcloud代理）
`VERTEX_AI_PROJECT`	否	-	谷歌云项目
`VERTEX_AI_LOCATION`	没有	`us-east4`	顶点AI区域

注：有关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

克劳德将：

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

高级搜索

问克劳德：

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

克劳德将：

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

后续问题

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

克劳德将：

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

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

🔐 安全

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

最佳实践

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

安全级别

方法	安全	设置
配置中的明文	❌ 可怜	容易
环境变量	✅ 好	简单
Docker环境文件	✅✅ 更好	中等
macOS钥匙扣	✅✅✅ 最佳	中等

看 安全.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

克劳德看不见工具

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

搜索未返回任何结果

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

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

🤝 贡献

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

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

📜 许可证

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

🔗 资源

🚀 快速参考

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容器化
✅ 完整记录
✅ 类型安全
✅ 安全强化

使用说明

LiteLLM矢量存储MCP服务器

✨ 特性

🚀 快速开始

🐳 Docker镜像

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

验证设置

与克劳德一起测试

📚 文档

用户指南

开发者指南

🎯 可用工具

litellm_list_vector_stores

litellm_search_vector_store

🐳 Docker部署

构建与运行

分布

🔧 配置

环境变量

测试配置

🎓 MCP最佳实践

📖 用法示例

基本搜索

高级搜索

后续问题

🔐 安全

推荐设置（安全）

最佳实践

安全级别

🛠️ 故障排除

身份验证失败错误

服务器无法启动

克劳德看不见工具

搜索未返回任何结果

🤝 贡献

📜 许可证

🔗 资源

🚀 快速参考

Docker命令

Python命令

克劳德集成

📈 状态

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

代码分析服务器

本地LLM模型控制协议

文档搜索服务

`litellm_list_vector_stores`

`litellm_search_vector_store`