Vectara MCP Server

🔌 与Claude Desktop和其他任何MCP客户端兼容！

Vectara MCP也与其他任何MCP客户端兼容。

模型上下文协议（MCP）是一个开放标准，使AI系统能够无缝地与各种数据源和工具交互，促进安全的双向连接。

通过MCP协议，Vectara-MCP为任何代理应用程序提供快速、可靠的RAG访问，减少幻觉，由Vectara的可信RAG平台驱动。

安装

你可以直接从PyPI安装该包：

pip install vectara-mcp

快速开始

默认安全设置（HTTP/SSE带认证）

# 使用安全的HTTP传输启动服务器（默认）
python -m vectara_mcp
# 服务器运行在http://127.0.0.1:8000，并启用认证

本地开发模式（STDIO）

# 对于Claude Desktop或本地开发（安全性较低）
python -m vectara_mcp --stdio
# ⚠️ 警告：STDIO传输安全性较低。仅用于本地开发。

配置选项

# 自定义主机和端口
python -m vectara_mcp --host 0.0.0.0 --port 8080

# SSE传输模式
python -m vectara_mcp --transport sse --path /sse

# 禁用认证（危险 - 仅限开发）
python -m vectara_mcp --no-auth

传输模式

HTTP传输（默认 - 推荐）

• 安全性： 通过承载令牌内置认证
• 加密： 支持HTTPS
• 速率限制： 默认每分钟100个请求
• CORS保护： 可配置的来源验证
• 使用场景： 生产部署，云环境

SSE传输

• 流式传输： 用于实时更新的服务器发送事件
• 认证： 支持承载令牌
• 兼容性： 与旧版MCP客户端兼容
• 使用场景： 实时流应用

STDIO传输

• ⚠️ 安全警告： 没有传输层安全
• 性能： 本地通信低延迟
• 使用场景： 本地开发，Claude Desktop
• 要求： 必须显式启用--stdio标志

环境变量

# 必需
export VECTARA_API_KEY="your-api-key"

# 可选
export VECTARA_AUTHORIZED_TOKENS="token1,token2"  # 额外的认证令牌
export VECTARA_ALLOWED_ORIGINS="http://localhost:*,https://app.example.com"
export VECTARA_TRANSPORT="http"  # 默认传输模式
export VECTARA_AUTH_REQUIRED="true"  # 强制认证

认证

HTTP/SSE传输

当使用HTTP或SSE传输时，默认需要认证：

# 使用curl和承载令牌
curl -H "Authorization: Bearer $VECTARA_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST http://localhost:8000/call/ask_vectara \
     -d '{"query": "什么是Vectara？", "corpus_keys": ["我的语料库"]}'

# 使用X-API-Key头（替代方案）
curl -H "X-API-Key: $VECTARA_API_KEY" \
     http://localhost:8000/sse

禁用认证（仅限开发）

# ⚠️ 绝不在生产环境中使用
python -m vectara_mcp --no-auth

可用工具

API密钥管理

• setup_vectara_api_key: 配置并验证会话中的Vectara API密钥（一次性设置）。

  参数：

  • api_key: str, 你的Vectara API密钥 - 必需。

  返回：

  • 成功确认，带有掩码的API密钥或验证错误。

• clear_vectara_api_key: 清除服务器内存中存储的API密钥。

  返回：

  • 确认消息。

查询工具

• ask_vectara: 使用Vectara运行RAG查询，返回生成的回答和搜索结果。

  参数：

  • query: str, 要运行的用户查询 - 必需。
  • corpus_keys: list[str], 用于搜索的Vectara语料库键列表 - 必需。
  • n_sentences_before: int, 在上下文中包含答案前的句子数 - 可选，默认为2。
  • n_sentences_after: int, 在上下文中包含答案后的句子数 - 可选，默认为2。
  • lexical_interpolation: float, 要使用的词汇插值量 - 可选，默认为0.005。
  • max_used_search_results: int, 要使用的最大搜索结果数 - 可选，默认为1
  • generation_preset_name: str, 要使用的生成预设名称 - 可选，默认为"vectara-summary-table-md-query-ext-jan-2025-gpt-4o"。
  • response_language: str, 响应的语言 - 可选，默认为"eng"。

  返回：

  • 来自Vectara的响应，包括生成的答案和搜索结果。

• search_vectara: 使用Vectara运行语义搜索查询，不进行生成。

  参数：

  • query: str, 要运行的用户查询 - 必需。
  • corpus_keys: list[str], 用于搜索的Vectara语料库键列表 - 必需。
  • n_sentences_before: int, 在上下文中包含答案前的句子数 - 可选，默认为2。
  • n_sentences_after: int, 在上下文中包含答案后的句子数 - 可选，默认为2。
  • lexical_interpolation: float, 要使用的词汇插值量 - 可选，默认为0.005。

  返回：

  • 来自Vectara的响应，包括匹配的搜索结果。

分析工具

• correct_hallucinations: 使用Vectara的VHC（Vectara幻觉校正）API识别并纠正生成文本中的幻觉。

  参数：

  • generated_text: str, 要分析幻觉的生成文本 - 必需。
  • documents: list[str], 要比较的源文档列表 - 必需。
  • query: str, 导致生成文本的原始用户查询 - 可选。

  返回：

  • 包含纠正文本和详细纠正信息的JSON格式字符串。

• eval_factual_consistency: 使用Vectara的专用事实一致性评估API评估生成文本相对于源文档的事实一致性。

  参数：

  • generated_text: str, 要评估事实一致性的生成文本 - 必需。
  • documents: list[str], 要比较的源文档列表 - 必需。
  • query: str, 导致生成文本的原始用户查询 - 可选。

  返回：

  • 包含事实一致性评估结果和评分的JSON格式字符串。

注意： 需要先使用setup_vectara_api_key工具或VECTARA_API_KEY环境变量配置API密钥。

与Claude Desktop配置

要与Claude Desktop一起使用，请更新配置以使用STDIO传输：

{
  "mcpServers": {
    "Vectara": {
      "command": "python",
      "args": ["-m", "vectara_mcp", "--stdio"],
      "env": {
        "VECTARA_API_KEY": "your-api-key"
      }
    }
  }
}

或者使用uv：

{
  "mcpServers": {
    "Vectara": {
      "command": "uv",
      "args": ["tool", "run", "vectara-mcp", "--stdio"]
    }
  }
}

注意： Claude Desktop需要STDIO传输。虽然不如HTTP安全，但对于本地桌面使用是可以接受的。

在Claude Desktop应用中的使用

完成安装并配置Claude桌面应用后，必须完全关闭并重新打开Claude桌面应用才能看到Vectara-mcp服务器。你应该在应用左下角看到一个锤子图标，表示可用的MCP工具，点击锤子图标可以查看更多关于Vectara搜索和提取工具的详细信息。

现在Claude将拥有对Vectara-mcp服务器的完全访问权限，包括所有六个Vectara工具。

安全设置工作流程

首次设置（每个会话一次）：

1. 安全配置你的API密钥：

setup-vectara-api-key
API key: [your-vectara-api-key]

设置完成后，无需暴露API密钥即可使用任何工具：

Vectara工具示例

1. 带有生成的RAG查询：

ask-vectara
Query: 谁是Amr Awadallah？
Corpus keys: ["your-corpus-key"]

2. 仅语义搜索：

search-vectara
Query: 纽约市的活动？
Corpus keys: ["your-corpus-key"]

3. 幻觉检测与校正：

correct-hallucinations
Generated text: [要检查的文本]
Documents: ["source1", "source2"]

4. 事实一致性评估：

eval-factual-consistency
Generated text: [要评估的文本]
Documents: ["reference1", "reference2"]

安全最佳实践

1. 生产中始终使用HTTP传输 - 不要将STDIO传输暴露到网络上
2. 保持认证启用 - 仅在本地测试时禁用--no-auth
3. 生产中使用HTTPS - 部署在具有TLS终止的反向代理后面
4. 正确配置CORS - 设置VECTARA_ALLOWED_ORIGINS以限制访问
5. 定期轮换API密钥 - 更新VECTARA_API_KEY和VECTARA_AUTHORIZED_TOKENS
6. 监控速率限制 - 默认每分钟100个请求，根据需要调整

详情参见SECURITY.md中的详细安全指南。

支持

对于问题、疑问或贡献，请访问： https://github.com/vectara/vectara-mcp