Mcpcosmosdb

🚀 MCP CosmosDB - Azure CosmosDB MCP Server

A comprehensive Model Context Protocol (MCP) server for Azure CosmosDB database operations. This server offers 8 powerful tools for document database analysis, container discovery, and data querying via the MCP protocol.

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• An Azure CosmosDB database with a connection string
• An MCP-compatible client (e.g., Claude Desktop, Cursor IDE)

⚙️ Configuration

Required Environment Variables

Installation Options

Option 1: NPX (Recommended)

No installation is required! Configure your MCP client as follows:

{
  "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"
      }
    }
  }
}

Option 2: Local Development

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

Then configure it with the local path:

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

✨ Features

MCP CosmosDB offers 8 comprehensive tools for Azure CosmosDB operations:

1. 🗄️ List Databases - mcp_list_databases

List all databases in the CosmosDB account.

2. 📦 List Containers - mcp_list_containers

List all containers in the current database.

3. 📋 Container Information - mcp_container_info

Get detailed information about a specific container, including the partition key, indexing policy, and throughput settings.

4. 📊 Container Statistics - mcp_container_stats

Get statistics about a container, including the document count, size estimation, and partition key distribution.

5. 🔍 Execute SQL Query - mcp_execute_query

Execute SQL queries against CosmosDB containers with parameters and performance metrics.

6. 📄 Get Documents - mcp_get_documents

Retrieve documents from containers with optional filtering and partition key targeting.

7. 🎯 Get Document by ID - mcp_get_document_by_id

Retrieve a specific document by its ID and partition key.

8. 🏗️ Schema Analysis - mcp_analyze_schema

Analyze the document schema structure in containers to understand data patterns.

💻 Usage Examples

Basic Usage

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

Advanced Usage

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

Optional Configuration

Configuration Examples

Production Environment:

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

CosmosDB Emulator (Local):

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

Advanced Configuration:

{
  "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"
  }
}

📚 Documentation

Troubleshooting

Connection Issues

• Invalid connection string: Verify that the OCONNSTRING format includes AccountEndpoint and AccountKey.
• Database not found: Check that COSMOS_DATABASE_ID matches an existing database.
• Request timeout: Increase COSMOS_MAX_RETRY_WAIT_TIME or check your network.

Query Issues

• Cross partition query required: Set enable_cross_partition: true in the query parameters.
• Query timeout: Reduce sample sizes or add specific filters.
• Partition key required: Specify the partition_key for single-partition operations.

CosmosDB Emulator

1. Install the Azure CosmosDB Emulator.
2. Start the emulator on port 8081.
3. Use the default emulator connection string.
4. Create a database and containers for testing.

Development

npm test          # Run tests
npm run build     # Build the project
npm start         # Development mode

Architecture

Project Structure:

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

Key Features:

• ⚡ Connection management with retry logic
• 🛡️ Comprehensive error handling
• 📊 Performance metrics and request charges
• 🔧 Environment-based configuration
• 📋 Intelligent schema analysis

Important Notes

⚠️ Important Note

• Use exact container names as in CosmosDB.
• Partition keys are required for optimal performance.
• Cross-partition queries can be expensive; use filters.
• Monitor RU consumption.
• Store connection strings securely.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/name).
3. Make changes and add tests.
4. Ensure the tests pass (npm test).
5. Commit your changes (git commit -m 'Add feature').
6. Push and open a Pull Request.

📄 License

This project is under the MIT License. See the LICENSE file for details.

🏷️ Tags & Keywords

Database: 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

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

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

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

🙏 Acknowledgments

• Model Context Protocol SDK
• @azure/cosmos
• Inspired by MCPQL

🎯 MCP CosmosDB provides comprehensive Azure CosmosDB database analysis through the Model Context Protocol. Ideal for developers and data analysts working with CosmosDB! 🚀