MCP Cosmos Db

MCP CosmosDB-Azure CosmosDB MCP服务器

 ](https://nodejs.org/)  ](https://github.com/hendrickcastro/MCPCosmosDB/stargazers) ](https://github.com/hendrickcastro/MCPCosmosDB/issues) ](https://github.com/hendrickcastro/MCPCosmosDB/network)        

全面 模型上下文协议（MCP） 服务器 Azure宇宙数据库 数据库操作。该服务器通过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 
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

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

📋 使用示例

集装箱分析

// List all containers
const containers = await mcp_list_containers();

// Get container information
const containerInfo = await mcp_container_info({ 
  container_id: "users" 
});

// Get container statistics
const stats = await mcp_container_stats({ 
  container_id: "users",
  sample_size: 1000
});

查询数据

// Execute SQL query
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
});

// Get documents with filters
const documents = await mcp_get_documents({
  container_id: "orders",
  filter_conditions: { "status": "completed", "year": 2024 },
  limit: 100
});

文档操作

// Get specific document
const document = await mcp_get_document_by_id({
  container_id: "users",
  document_id: "user-123",
  partition_key: "user-123"
});

// Analyze schema
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          # Run tests
npm run build     # Build project
npm start         # Development mode

🏗️ 建筑

项目结构：

src/
├── tools/                    # Tool implementations
│   ├── containerAnalysis.ts  # Container operations
│   ├── dataOperations.ts     # Data queries
│   └── types.ts              # Type definitions
├── db.ts                     # CosmosDB connection
├── server.ts                 # MCP server setup
└── tools.ts                  # Tool definitions

主要特点：

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

📝 重要说明

• 容器ID：使用与CosmosDB中相同的确切名称
• 分区密钥：最佳性能所需
• 跨分区查询：可能很贵；使用过滤器
• 请求收费：监控RU消耗
• 安全：安全地存储连接字符串

🤝 贡献

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

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🏷️ 标签和关键字

数据库： 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

🙏 致谢

• 模型上下文协议SDK
• @蔚蓝/宇宙
• 源于 MCPQL

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