Mcpcosmosdb

🚀 MCP CosmosDB - Azure CosmosDB MCP 服务器

MCP CosmosDB 是一个用于 Azure CosmosDB 数据库操作的综合 模型上下文协议 (MCP) 服务器。该服务器通过 MCP 协议提供了 8 种强大的工具，可用于文档数据库分析、容器发现和数据查询。

🚀 快速开始

前提条件

• Node.js 18 及以上版本和 npm
• 具备连接字符串的 Azure CosmosDB 数据库
• 兼容 MCP 的客户端（Claude Desktop、Cursor IDE 等）

⚙️ 配置

必需的环境变量

安装选项

选项 1：NPX（推荐）

无需安装！配置您的 MCP 客户端：

{
  "mcpServers": {
    "mcp-cosmosdb": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/MCPCosmosDB"],
      "env": {
        "OCONNSTRING": "AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-account-key-here;",
        "COSMOS_DATABASE_ID": "your-database-name"
      }
    }
  }
}

选项 2：本地开发

git clone <your-repo-url>
cd MCPCosmosDB
npm install && npm run build

然后使用本地路径进行配置：

{
  "mcpServers": {
    "mcp-cosmosdb": {
      "command": "node",
      "args": ["path/to/MCPCosmosDB/dist/server.js"],
      "env": {
        "OCONNSTRING": "your-connection-string",
        "COSMOS_DATABASE_ID": "your-database-name"
      }
    }
  }
}

✨ 主要特性

MCP CosmosDB 为 Azure CosmosDB 操作提供了 8 种全面的工具：

1. 🗄️ 列出数据库 - mcp_list_databases

列出 CosmosDB 账户中的所有数据库。

2. 📦 列出容器 - mcp_list_containers

列出当前数据库中的所有容器。

3. 📋 容器信息 - mcp_container_info

获取特定容器的详细信息，包括分区键、索引策略和吞吐量设置。

4. 📊 容器统计信息 - mcp_container_stats

获取容器的统计信息，包括文档计数、大小估计和分区键分布。

5. 🔍 执行 SQL 查询 - mcp_execute_query

使用参数和性能指标对 CosmosDB 容器执行 SQL 查询。

6. 📄 获取文档 - mcp_get_documents

从容器中检索文档，可选择进行过滤和指定分区键。

7. 🎯 按 ID 获取文档 - mcp_get_document_by_id

通过文档 ID 和分区键检索特定文档。

8. 🏗️ 模式分析 - mcp_analyze_schema

分析容器中的文档模式结构，以了解数据模式。

💻 使用示例

容器分析

// 列出所有容器
const containers = await mcp_list_containers();

// 获取容器信息
const containerInfo = await mcp_container_info({ 
  container_id: "users" 
});

// 获取容器统计信息
const stats = await mcp_container_stats({ 
  container_id: "users",
  sample_size: 1000
});

查询数据

// 执行 SQL 查询
const result = await mcp_execute_query({
  container_id: "products",
  query: "SELECT * FROM c WHERE c.category = @category AND c.price > @minPrice",
  parameters: { "category": "electronics", "minPrice": 100 },
  max_items: 50
});

// 获取过滤后的文档
const documents = await mcp_get_documents({
  container_id: "orders",
  filter_conditions: { "status": "completed", "year": 2024 },
  limit: 100
});

文档操作

// 获取特定文档
const document = await mcp_get_document_by_id({
  container_id: "users",
  document_id: "user-123",
  partition_key: "user-123"
});

// 分析模式
const schema = await mcp_analyze_schema({
  container_id: "products",
  sample_size: 500
});

可选配置

配置示例

生产环境：

{
  "env": {
    "OCONNSTRING": "AccountEndpoint=https://mycompany-prod.documents.azure.com:443/;AccountKey=your-production-key;",
    "COSMOS_DATABASE_ID": "ProductionDB"
  }
}

CosmosDB 模拟器（本地）：

{
  "env": {
    "OCONNSTRING": "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;",
    "COSMOS_DATABASE_ID": "TestDB"
  }
}

高级配置：

{
  "env": {
    "OCONNSTRING": "AccountEndpoint=https://mycompany.documents.azure.com:443/;AccountKey=your-key;",
    "COSMOS_DATABASE_ID": "MyDatabase",
    "COSMOS_MAX_RETRY_ATTEMPTS": "15",
    "COSMOS_MAX_RETRY_WAIT_TIME": "60000"
  }
}

🚨 故障排除

连接问题

• 连接字符串无效：验证 OCONNSTRING 格式是否包含 AccountEndpoint 和 AccountKey
• 未找到数据库：检查 COSMOS_DATABASE_ID 是否与现有数据库匹配
• 请求超时：增加 COSMOS_MAX_RETRY_WAIT_TIME 或检查网络

查询问题

• 需要跨分区查询：在查询参数中设置 enable_cross_partition: true
• 查询超时：减小样本大小或添加特定过滤器
• 需要分区键：为单分区操作指定 partition_key

CosmosDB 模拟器

1. 安装 Azure CosmosDB 模拟器
2. 在端口 8081 上启动模拟器
3. 使用默认的模拟器连接字符串
4. 创建用于测试的数据库和容器

🧪 开发

npm test          # 运行测试
npm run build     # 构建项目
npm start         # 开发模式

🔧 技术细节

项目结构

src/
├── tools/                    # 工具实现
│   ├── containerAnalysis.ts  # 容器操作
│   ├── dataOperations.ts     # 数据查询
│   └── types.ts              # 类型定义
├── db.ts                     # CosmosDB 连接
├── server.ts                 # MCP 服务器设置
└── tools.ts                  # 工具定义

关键特性

• ⚡ 具备重试逻辑的连接管理
• 🛡️ 全面的错误处理
• 📊 性能指标和请求费用
• 🔧 基于环境的配置
• 📋 智能模式分析

📝 重要提示

⚠️ 重要提示

• 容器 ID：使用与 CosmosDB 中完全一致的名称
• 分区键：为获得最佳性能，操作时需要指定分区键
• 跨分区查询：可能会产生较高的成本，请使用过滤器
• 请求费用：监控 RU 消耗
• 安全性：安全存储连接字符串

🤝 贡献

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/name)
3. 进行更改并添加测试
4. 确保测试通过 (npm test)
5. 提交更改 (git commit -m 'Add feature')
6. 推送并打开拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🏷️ 标签与关键词

数据库相关

cosmosdb azure-cosmosdb nosql document-database database-analysis database-tools azure database-management database-operations data-analysis

MCP 与 AI 相关

model-context-protocol mcp-server mcp-tools ai-tools claude-desktop cursor-ide anthropic llm-integration ai-database intelligent-database

技术相关

typescript nodejs npm-package cli-tool database-client nosql-client database-sdk rest-api json-api database-connector

特性相关

container-analysis document-operations sql-queries schema-analysis query-execution database-search data-exploration database-insights partition-management throughput-analysis

使用场景相关

database-development data-science business-intelligence database-migration schema-documentation performance-analysis data-governance database-monitoring troubleshooting automation

🙏 致谢

• Model Context Protocol SDK
• @azure/cosmos
• 灵感来源于 MCPQL

🎯 MCP CosmosDB 通过模型上下文协议提供全面的 Azure CosmosDB 数据库分析。非常适合使用 CosmosDB 的开发人员和数据分析师！ 🚀