Astra DB MCP Server

Astra DB MCP 服务

用于与 Astra DB 交互的模型上下文协议（MCP）服务。MCP 通过允许大模型以 Agent 的身份与外部系统交互，扩展其能力。

前提条件

你需要有一个正在运行的 Astra DB 数据库。如果还没有，可以在此处创建一个免费数据库。从那里，你可以获取所需的两项内容：

1. Astra DB 应用令牌
2. Astra DB API 端点

若要了解如何获取这些内容，请阅读入门文档。

添加到 MCP 客户端

下面介绍如何将此服务添加到 MCP 客户端。

IBM Bob

对于 IBM Bob IDE，请按照此文档中的步骤操作。

对于 IBM Bob Shell，请按照此文档中的步骤操作。

Claude Desktop

若要将其添加到 Claude Desktop，请前往“Preferences” -> “Developer” -> “Edit Config”，然后将以下 JSON 代码块添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "astra-db-mcp": {
      "command": "npx",
      "args": ["-y", "@datastax/astra-db-mcp"],
      "env": {
        "ASTRA_DB_APPLICATION_TOKEN": "your_astra_db_token",
        "ASTRA_DB_API_ENDPOINT": "your_astra_db_endpoint"
      }
    }
  }
}

可选的 Keyspace 配置： 默认情况下，此服务使用底层 Astra DB 库中配置的 keyspace（通常为 default_keyspace）。如果需要连接到特定 keyspace，可以将 ASTRA_DB_KEYSPACE 变量添加到上方的 env 对象中，如下所示：

"env": {
  "ASTRA_DB_APPLICATION_TOKEN": "your_astra_db_token",
  "ASTRA_DB_API_ENDPOINT": "your_astra_db_endpoint",
  "ASTRA_DB_KEYSPACE": "your_desired_keyspace"
}

Windows PowerShell 用户： npx 是批处理命令，因此请按如下方式修改 JSON：

  "command": "cmd",
  "args": ["/k", "npx", "-y", "@datastax/astra-db-mcp"],

Cursor

若要将其添加到 Cursor，请前往“Settings” -> “Cursor Settings” -> “MCP”。

然后，点击“+ Add New MCP Server”按钮添加服务，随后应会打开一个 mcp.json 文件。

提示：~/.cursor/mcp.json 是全局 MCP 设置文件，此外还有一个针对项目的 .cursor/mcp.json 文件。 你可能需要将此 MCP 服务安装到针对项目的文件中。

添加与 Claude Desktop 说明中所示相同的 JSON。

或者，你可能会看到一个向导，可在其中输入以下值（适用于基于 Unix 的系统）：

• 名称：任意名称
• 类型：命令
• 命令：

env ASTRA_DB_APPLICATION_TOKEN=your_astra_db_token ASTRA_DB_API_ENDPOINT=your_astra_db_endpoint npx -y @datastax/astra-db-mcp

注意：ASTRA_DB_KEYSPACE 是可选的。如果省略，将使用 Astra DB 库中配置的默认 keyspace。

添加后，你的编辑器便会与 Astra DB 数据库完全连接。

可用工具

此服务提供一套全面的工具，涵盖集合、向量搜索、表、Keyspace 和管理功能：

📁 集合与文档

• GetCollections：获取当前键空间中的所有集合
• GetCollectionInfo：查看集合选项、向量设置和默认 ID 配置
• CreateCollection：创建集合，并配置向量选项、距离度量（cosine、euclidean、dot_product）和自动向量化
• UpdateCollection：更新或重命名集合
• DeleteCollection：删除集合
• EstimateDocumentCount：获取集合中的文档数量估算值
• ListRecords：列出记录，可选排序、分页（skip）和投影
• GetRecord：按 ID 获取特定记录
• CreateRecord：插入单个文档
• UpdateRecord：更新记录
• DeleteRecord：按 ID 删除记录
• FindRecord：按字段值精确匹配查找记录
• FindWithFilter：使用 MongoDB 风格的筛选运算符（$and、$or、$gt、$in、$exists 等）进行丰富查询
• FindDistinctValues：查找集合中特定字段的不同值
• BulkCreateRecords：批量插入多个文档
• BulkUpdateRecords：批量更新多条记录
• BulkDeleteRecords：批量删除多条记录

🧠 向量搜索与重排序

• FindWithVector：进行稠密向量相似度搜索，可选元数据筛选、相似度分数和投影
• FindWithVectorize：使用 Astra DB Vectorize 无服务器嵌入进行自然语言搜索
• FindAndRerank：混合搜索（词法搜索 + 稠密向量／自动向量化），并获取服务端重排序分数
• VectorSearch：进行向量相似度搜索，可设置 minScore 阈值和投影
• HybridSearch：结合稠密向量相似度和文本搜索，并采用加权评分

📊 表（Astra DB Data API v2）

• ListTables：列出键空间中的所有结构化表
• CreateTable：根据列定义和主键创建类型化表
• AlterTable：添加或删除列（包括向量列）
• DropTable：删除表
• QueryTable：查询表行，可使用筛选条件、排序、投影和分页
• InsertTableRow：向表中插入单行或批量插入多行
• UpdateTableRow：更新表中符合条件的行
• DeleteTableRow：删除表中符合条件的行
• CreateTableIndex：在表列上创建二级索引
• CreateTableVectorIndex：在表列上创建向量索引，并指定相似度度量

🔑 键空间与管理

• ListKeyspaces：列出数据库中的所有键空间
• CreateKeyspace：创建新键空间，可选自动切换
• DropKeyspace：删除键空间
• UseKeyspace：切换后续操作所使用的当前工作键空间
• GetCurrentKeyspace：查看当前键空间名称
• ListEmbeddingProviders：查看受支持的嵌入模型和提供商
• ListRerankingProviders：查看受支持的重排序模型
• GetDatabaseInfo：获取环境元数据（ID、区域、状态、键空间）

🛠️ 实用工具

• OpenBrowser：打开浏览器以进行身份验证／设置
• HelpAddToClient：获取 MCP 客户端安装帮助

更新日志

本项目的所有重要更改都将记录在此文件中。 格式基于 Keep a Changelog，本项目遵循语义化版本。

运行评估

evals 软件包会加载一个 MCP 客户端，然后运行 index.ts 文件，因此无需在测试之间重新构建。你可以在 npx 命令前添加环境变量来加载它们。完整文档请参阅此处。

OPENAI_API_KEY=your-key  npx mcp-eval evals.ts tools.ts

❤️ 贡献者

Badges