MCP CosmosDB - Azure CosmosDB MCP Server

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

🚀 Quick Start

Prerequisites

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

⚙️ Configuration

Required Environment Variables

Installation Options

Option 1: NPX (Recommended)

No installation needed! Configure your MCP client:

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

🛠️ Available Tools

MCP CosmosDB provides 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 partition key, indexing policy, and throughput settings.

4. 📊 Container Statistics - mcp_container_stats

Get statistics about a container including 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 document schema structure in containers to understand data patterns.

📋 Usage Examples

Container Analysis

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

Querying Data

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

Document Operations

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

🚨 Troubleshooting

Connection Issues:

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

Query Issues:

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

CosmosDB Emulator:

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

🧪 Development

npm test          # Run tests
npm run build     # Build 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

• Container IDs: Use exact names as in CosmosDB
• Partition Keys: Required for optimal performance
• Cross-Partition Queries: Can be expensive; use filters
• Request Charges: Monitor RU consumption
• Security: Store connection strings securely

🤝 Contributing

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

📄 License

MIT License - see 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. Perfect for developers and data analysts working with CosmosDB! 🚀