Calypso 多模态 RAG MCP 服务器

最简单的托管式多模态 RAG MCP 服务器，适用于 Claude Desktop、Cursor 和智能体工作流。

一条 npx 命令即可。由 Gemini File Search 驱动。原生处理 PDF、截图、图表、示意图和图片，并附带可验证的引用。

为 Claude、Cursor、Windsurf 和自定义智能体添加托管式多模态 RAG 的最简单方式。

• 超简单配置：npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-your-key-here

• 真正的多模态 RAG：通过 Gemini File Search 原生处理文本和视觉内容

• 上传与查询：专用于持久知识文件和批量上传的工具

• 多轮对话：支持上下文感知的回答，可通过 /new 重置

• 可发现的工作流：为安全的 RAG、上传和摄取流程提供资源和提示词

GitHub | 文档 | Smithery | 官方 MCP 注册表

标签：multimodal-rag、easiest-mcp-rag、gemini-rag、hosted-rag-mcp、mcp-server

与其将每个智能体或工作流接入一次性的文档搜索栈，不如使用此 MCP 作为面向智能体的入口，连接一个可复用的答案层：上传一次源材料，即可跨文本和视觉内容检索，并返回带有用户可验证证据的答案。

快速开始（最简单方式）

# One-liner with npx
npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-your-key-here"

或使用环境变量：

CALYPSO_API_KEY="sk-..." npx -y @calypsohq/multimodal-rag-mcp-server

然后使用下面的配置示例，将相同的命令添加到 Claude Desktop、Cursor 或 Smithery。

Related MCP server: RAG-Anything MCP Server

为什么选择 Calypso

Calypso 专为希望获得最简单托管式多模态 RAG MCP 服务器的团队而构建：无需本地向量栈、无需 Docker Compose、无需在智能体提出有据可依的问题之前先搭建自定义 OCR 或图像处理流水线。

如果您想要最简单的托管式多模态 RAG MCP 服务器，从这里开始。

您将获得

• 具有多轮记忆能力的生产级多模态 RAG 智能体

• 内置单文件上传和批量知识上传工具

• 自动发现您团队的 RAG 变体和知识桶

• 带有来源引用和检索元数据的可验证引用

• 用于安全工作流的只读资源和可复用提示词

为什么多模态优先的 RAG

大多数公司知识不仅仅是文本。答案往往分散在设置截图、PDF 表格、产品示意图、帮助中心页面或报告中的图表里。Calypso 将完整的知识面打包到单一检索层中，让智能体能够提出有据可依的问题，而不是依赖通用模型记忆进行猜测。

• 搜索用户实际依赖的格式：文档、PDF、截图、图表、示意图、产品图片、支持文章、手册、政策、常见问题解答和报告。

• 在模型作答之前先建立依据：Gemini File Search 先检索相关的文本和视觉上下文，然后 RAG 智能体基于这些源材料作答。

• 展示证据链：回答可以包含来源引用、页面感知的依据和检索元数据，让用户在信任之前先进行验证。

• 使用元数据限定检索范围：使用工作区、团队、客户、语言、文件类型、状态或其他元数据来保持回答的相关性，而无需复制知识库。

• 在任意位置复用同一知识层：将 Cursor、Claude Desktop、AI 智能体、n8n 工作流、产品界面、支持流程和网站体验连接到同一个有源支撑的层。

在实践中，这意味着您的智能体可以回答如下问题：

• "解释这张设置截图和附带的政策 PDF。支持代表下一步应该做什么？"

• "这份入职 PDF 中关于审批规则说了什么？"

• "为什么这个设置界面失败了？"

• "将定价图表与我们的套餐文档进行比较，并推荐合适的层级。"

• "总结适用于此支持工单的政策。"

• "根据我们的定价文档，哪个产品套餐适合这个客户？"

• "比较图示的摄取流程与检索流程。"

此 MCP 的功能

使用 calypso-rag-agent，您可以：

• 针对已配置的 Calypso 知识库提出有据可依的问题

• 使用可选的 model 参数选择任何已发现的团队 RAG 变体

• 通过原生 /v1/responses 对话模型继续多轮对话

• 使用 /new 重置对话上下文

• 使用与 calypso-rag-agent 相同的兼容 OpenAI 的 Responses 端点

• 发现内置资源和提示词，用于受支持的 Calypso 工作流

要求

• Node.js 18+

• 服务器使用 Web Fetch API 原语（fetch、Headers、Request、Response、FormData、Blob 和 File）进行 API 调用并实现 SDK 兼容性。该包会在启动时为仅暴露部分 Node 18+ Web API 表面的 MCP 运行时引导缺失的全局对象。

• 一个 Calypso API 端点，需暴露：

  • POST /v1/responses

  • GET /v1/rag-agent/models

  • GET /v1/knowledge/buckets

  • POST /v1/knowledge/files/upload-session

  • POST /v1/knowledge/files/upload-session/{session_id}/finalize

  • POST /v1/knowledge/files:batch/upload-session

  • POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize

  • GET /v1/knowledge/batches/{batch_id}

• 一个 Calypso API 密钥（sk-...）

配置

环境变量：

• CALYPSO_API_KEY（必填）

• CALYPSO_API_BASE_URL（可选，默认 https://api.calypso.so/v1）

CLI 标志：

• --api-key

• --api-base-url

配置优先级：

1. CLI 标志 / Smithery 提供的命令参数

2. 环境变量

3. 默认基础 URL（https://api.calypso.so/v1）

使用 npx 运行

npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-..."

使用环境变量运行

env CALYPSO_API_KEY="sk-..." CALYPSO_API_BASE_URL="https://api.calypso.so/v1" npx -y @calypsohq/multimodal-rag-mcp-server

在 Cursor 中配置

添加一个新的 MCP 服务器（命令类型），如下所示：

npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1

在 Claude Desktop 中配置

1. 打开 Claude Desktop MCP 配置

在 Claude Desktop 中：

Claude -> 设置 -> 开发者 -> 编辑配置

在 macOS 上，该文件通常位于：

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop 使用 claude_desktop_config.json 作为桌面 MCP 服务器配置。Claude Code 使用单独的配置位置，例如 ~/.claude.json 或项目级别的 .mcp.json。

2. 添加 Calypso MCP 服务器

将以下内容粘贴到 claude_desktop_config.json 中：

{
  "mcpServers": {
    "Calypso Multimodal RAG": {
      "command": "npx",
      "args": [
        "-y",
        "@calypsohq/multimodal-rag-mcp-server"
      ],
      "env": {
        "CALYPSO_API_KEY": "sk-your-calypso-api-key",
        "CALYPSO_API_BASE_URL": "https://api.calypso.so/v1"
      }
    }
  }
}

将：

• sk-your-calypso-api-key

替换为您的真实 Calypso API 密钥。

3. 完全重启 Claude Desktop

完全退出 Claude Desktop，然后重新打开。

不要只关闭窗口。在 macOS 上：

Cmd + Q

重启后，MCP 应出现在 Claude 中，并带有以下可用工具：

• calypso-rag-agent

• calypso-list-buckets

• calypso-upload-file

• calypso-upload-files-batch

可选：将 Claude Artifacts 保存到您的 Mac

Calypso 提供托管式多模态 RAG 工具。它不会将生成的报告、摘要、CSV、JSON 文件或网络搜索产物直接写入您的本地计算机。

要让 Claude Desktop 在本地保存生成的文件，请在 Calypso 旁边添加标准的 filesystem MCP 服务器，并将其限制在专用的安全文件夹中。

先创建文件夹：

mkdir -p ~/Claude

然后将两个服务器都添加到 claude_desktop_config.json 中：

{
  "mcpServers": {
    "Calypso Multimodal RAG": {
      "command": "npx",
      "args": [
        "-y",
        "@calypsohq/multimodal-rag-mcp-server"
      ],
      "env": {
        "CALYPSO_API_KEY": "sk-your-calypso-api-key",
        "CALYPSO_API_BASE_URL": "https://api.calypso.so/v1"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Claude"
      ]
    }
  }
}

更改配置后，完全退出并重新打开 Claude Desktop。

示例提示词：

Use Calypso for the grounded RAG answer, then save the final report as /Users/yourname/Claude/report.md using the filesystem tool.

出于安全考虑，仅授予对专用文件夹（如 ~/Claude）的文件系统访问权限，而不是整个主目录。

Smithery

该服务器可在 Smithery 上获取，并通过桌面客户端使用的相同 npx 包路径启动。

Smithery 用户配置：

• calypsoApiKey（必填）

• calypsoApiBaseUrl（可选，默认为 https://api.calypso.so/v1）

Smithery 启动路径等同于：

npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1

仅在目标是自托管的 Calypso 兼容部署时使用 calypsoApiBaseUrl。云端默认值无需覆盖。

故障排查

• 缺少 API 密钥：提供 --api-key 或 CALYPSO_API_KEY

• 错误的 API 主机：确保 --api-base-url / CALYPSO_API_BASE_URL 以 /v1 结尾

• 自托管部署：仅当你未使用 https://api.calypso.so/v1 时才覆盖基础 URL

• Smithery 启动不匹配：使用打包的 npx -y @calypsohq/multimodal-rag-mcp-server 路径，而不是从新克隆中运行 node dist/index.js

• FormData is not defined 或 Headers is not defined：升级到最新包。MCP 服务器会在上传工具运行前引导缺失的 Web Fetch API 全局对象。

• /mnt/user-data/uploads/... 出现 ENOENT：该路径属于托管代理或附件沙箱，不一定属于 MCP 服务器。请改用 contentBase64 而不是 filePath 重试。

• 本地工件保存：Calypso 答案可以与 Claude Desktop 的 filesystem MCP 服务器一起使用，但必须明确要求 Claude 将最终输出保存到允许的本地路径。

选择 filePath 还是 contentBase64

对于本地 MCP 安装，请使用 filePath，包括使用本地命令启动此包的 Claude Desktop 和 Cursor 配置，例如：

npx -y @calypsohq/multimodal-rag-mcp-server

在这种设置下，MCP 服务器进程运行在你的机器上，并且可以读取同一用户账户可访问的路径。直接传入本地路径即可；服务器读取原始字节，并通过 Calypso 上传会话 URL 上传。你不需要对本地文件进行 base64 编码。

对于托管或远程 MCP 客户端，请使用 contentBase64，包括 Smithery 托管的服务器、浏览器/云端运行时、生成的内存内容以及智能体容器。在这些环境中，你 Mac 或工作站上的路径对 MCP 服务器进程不可读。

如果路径以 /mnt/user-data/uploads、/mnt/data、/mnt/attachments 或另一个托管沙箱前缀开头，除非此 MCP 服务器运行在同一个沙箱中，否则不要将其作为 filePath 发送。请改用 contentBase64 或其他内联字节源。

可用工具

calypso-rag-agent

直接访问 Calypso RAG 智能体。

说明：

• 它不会自动路由到其他 persona 或智能体。

• 它会在启动时自动发现 API 密钥可用的 calypso-rag-agent 模型变体。

• 使用可选的 model 参数选择命名变体，例如 calypso-rag-agent:pricing。

• 每个模型变体维护自己的 MCP 对话链，因此切换变体不会继续错误的线程。

• 它使用 POST /v1/responses 而不是 POST /v1/chat/completions。

• 首次交互创建一个命名对话，后续交互通过 previous_response_id 链接。

• 对于检索范围的问题，支持可选的 fileIds。新上传应使用持久知识上传工具，并等待索引就绪后再提问。

• 使用 /new 作为提示来重置 MCP 对话。

calypso-list-buckets

列出与所配置的 Calypso API 密钥关联的团队的存储桶。

说明：

• 使用 GET /v1/knowledge/buckets。

• 不接受 team_id；Calypso 从 API 密钥中推导团队范围。

• 返回桶 ID、slug、名称、状态、成员数、来源数和存储桶存储就绪状态。

• 默认仅显示活动存储桶。当你需要审计或清理已归档存储桶时，请传入 includeArchived: true。

• 当您需要选择目标存储桶时，请在 calypso-upload-file 或 calypso-upload-files-batch 之前使用此工具。

• calypso://rag-agent-models 可以告诉你哪些桶绑定到每个 RAG 变体，calypso-list-buckets 可以告诉你 API 密钥所属团队存在哪些桶。

示例：

{
  "includeArchived": false
}

calypso-get-file

根据文件 ID 获取一个知识文件的元数据和函数索引状态。

说明：

• 使用 GET /v1/knowledge/files/{file_id}。

• 将 calypso-list-buckets 中的不透明 fileId 解析为文件名、MMIME、大小、索引状态以及每个桶的同步状态。

• 设置 verify: true 可回调 verify: true 交叉验证（?verify=gemini）——较慢，但可在状态时提供权威结果。

示例：

{
  "fileId": "file_123",
  "verify": true
}

calypso-create-bucket

为“先创建后填充”的工作流创建一个空的桶。

说明：

• 使用 POST /v1/knowledge/buckets（要求后端已部署此端点，并且 API 密钥具有 knowledge:bucket:create 能力）。

• 服务器的缓存有规范：冲突会返回类型化错误 bucket_slug_exists。

• idempotencyKey 重放时返回已有桶而不是或多个错误。

• 上传操作仍然可以通过 bucketSlugs + createMissingBuckets 隐式创建桶；此工具用于先创建目标桶。

示例：

{
  "name": "Product docs",
  "slug": "product-docs",
  "idempotencyKey": "create-product-docs-1"
}

calypso-create-agent

创建绑定到一个或多个桶的 RAG 智能体变体。

说明：

• 使用 POST /v1/rag-agent/agents（要求后端已部署此端点且 API 密钥具有 rag:agent:create 能力）。

• 成功响应的核心是 model——直接将其传给 calypso-rag-agent。

• 桶绑定在服务器端验证：未知或已归档的桶返回 bucket_not_found；智能体 ID 冲突返回 agent_id_exists；计划的智能体上限返回 agent_limit_reached。

• 创建智能体会刷新模型目录，并发出 tools/list_changed 和 resources/list_changed 的 MCP 通知，因此无需重连即可使用新变体。

示例：

{
  "agentId": "support",
  "name": "Support agent",
  "bucketSlugs": ["product-docs"],
  "idempotencyKey": "create-support-agent-1"
}

calypso-uploadfile

将文件上传到持久化、基于桶的知识存储和索引管道中。

说明：

• 使用 POST /v1/knowledge/files/upload-session，将字节直接上传到存储，然后使用 POST /v1/knowledge/files/upload-session/{session_id}/finalize 完成上传。

• 上传使用 JSON 会话请求和签名的二进制 PUT 请求，而不是 multipart 表单上传。

• 返回文件和任务元数据，而不是聊天附件的 file_id。

• 必须是通过 bucketIds、bucketSlugs 或 bucket 指定的一个目标桶。

• 在本地 Claude Desktop/Cursor MCP 安装中，服务器可读取路径时，使用 filePath；在无法读取本地路径的托管或远程 MCP 客户端中，使用 contentBase64。

• 如果智能体看到一个路径如 /mnt/user-data/uploads/file.pdf，不应将其作为 filePath 发送，而应作为 content 发送。

• 支持可选的 title、tags、metadata 和 idempotencyKey。

• 通过 bucketId 或 bucketSlug 将上传路由到现有桶，或将 bucket 作为单 slug 快捷方式。

• 当你想让 Calypso 在bucket 当上传时创建缺失的 bucket 目标时，使用支持 createMissingBuckets: true 的 bucket slug。

• 可以选择等待索引到达就绪状态后再返回。

示例：

{
  "filename": "handbook.pdf",
  "mimeType": "application/pdf",
  "filePath": "/Users/me/Documents/handbook.pdf",
  "bucket": "support-handbook",
  "createMissingBuckets": true,
  "waitForIndexing": true
}

calypso-upload-files-batch

在一次请求中上传 1 到 100 个文件到持久化知识存储。

说明：

• 使用 POST /v1/knowledge/files:batch/upload-session，将每个接受的项直接上传到存储，然后使用 POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize 完成上传。

• 上传使用 JSON 会话请求和签名的二进制 PUT 请求，而不是 multipart 表单上传。

• 需要 batch；Calypso 使用它派生的 batch id 用于重试。

• 需要通过 bucketId、bucketSlug 或 bucket 指定一个共享的桶目标，除非每个项目都提供自己的桶目标。

• 支持共享 bucketIds、bucketSlugs、bucket 和 createMissingBuckets 默认值，并支持每个单个项目的覆盖。

• 对于支持读取每个路径的本地 Claude Desktop/Cursor MCP 安装，请使用 per-item 的 filePath；对于无法读取本地路径的托管或远程 MCP 客户端，请使用 per-item 的 contentBase64。

• 当未提供 clientFileId 时，会生成 Firestore 安全的 client_file_id 值。

• accepted 或 queued 表示上传已经是持久，但不一定可以立即查询。使用 waitForBatchReady: true 轮询 GET /v1/knowledge/batches/{batch_id}?include_items=true。

• 检查每个项目的 status、bucketSyncStatus 和 bucketSync，以区分已索引内容和可检索的桶就绪内容。

示例：

{
  "batchIdempotencyKey": "kb-seed-2026-06-04",
  "bucket": "support-handbook",
  "createMissingBuckets": true,
  "items": [
    {
      "filename": "faq.txt",
      "mimeType": "text/plain",
      "filePath": "/Users/me/Documents/faq.txt"
    }
  ],
  "waitForBatchReady": true
}

可用资源

calypso://server-info

只读的服务器元数据，包括包版本、API 基础 URL、传输方式、身份验证模型和暴露的能力。

calypso://rag-agent-models

只读的运行时目录，包含从所配置的 API 密钥发现的团队范围内的 calypso-rag-agent 模型变体，以及每个变体的活动 buckets、bucket_ids 和 missing_bucket_ids。如果无法进行发现，此资源将回退到基本的 calypso-rag-agent。

calupso://buckets

针对所配置的 API 密钥关联的团队的、可读取的存储桶运行时列表。在上传之前，检查存储桶 id/slug 和存储桶存储就绪状态。

calypso://workflows

针对支持的 RCP 和文件上传工作流提供的简洁指南。

calypso://security

有关 API 密钥、本地文件读取、上传和日志记录的操作安全说明。

可用提示词

• calypso-question：为 calypso-rag-agent 起草一个基于知识库的问题

• calypso-ingestion：为持久化知识库上传和后续查询做相应准备

• calypso-reset-conversation：使用 /new 开始一个干净的 RAG 线程

常见工作流（复制/粘贴）

知识检索

• 总结一个主题：

  • 总结我们文档中关于宣传计划审批的指导

• 询问具体答案：

  • 我们关于索引重试的文档描述了什么？

• 比较两个概念：

  • 比较当前架构中的文件索引和检索执行

• 开始新线程：

  • /new

多轮跟进

• 优化先前的回答：

  • 只关注摄取路径，忽略检索

• 要求来源或依据：

  • 解释哪些文档组件被涉及的原因

知识库史诗

• 发现存储桶：

  • 在选择目标存储前，先调用 calypso-list-buckets 或读取 calypso://buckets。

• 上传持久化知识：

  • 调用 calypso-upload-file，传入文件数据和可选 title、tags 或 metadata

  • 对于本地 Claude Desktop/Cursor MCP 安装，建议使用 filePath；对于无法读取本地路径的托管或远程 MCP 客户端，使用 contentBase64

• 将知识路由到存储桶：

  • 使用 bucket: "support-handbook" 指定单个目标，bucketSlugs指定多个基于 slug 的目标，或 bucketIds 在已有桶 id 时使用

• 按需创建存储桶目标：

  • 使用基于 slug 的存储桶分配且目标可能不存在时，添加 createMissingBuckets: true

• 等待索引完成：

  • 如果要工具通过索引完成后再返回，请添加 waitForIndexing: true

知识库批处理

• 上传多个持久化文件：

  • 调用 calypso-upload-files-batch，传入 items、batchIdempotencyKey 以及每个项目的 filePath（本地 MCP 安装时）；对于托管或远程 MCP 客户端，使用每个项目的 contentBase64

• 将批次路由到存储桶中：

  • 在工具调用中提供共享的 bucket、bucketSlugs、bucketIds 或 createMissingBuckets，然后仅在需要时按项目覆盖

• 等待可查询状态：

  • 使用 waitForBatchReady: true，并在查询刚上传的内容之前检查返回项目的 status 以及桶同步字段

提示

• 重新开始：使用 /new 重置 MCP 对话（新的 conversation_id 和触发的响应链）