The MCP CosmosDB server enables comprehensive management and analysis of Azure CosmosDB databases through the Model Context Protocol, providing 8 key tools:
• List Databases - Enumerate all databases in your CosmosDB account • List Containers - Display all containers within a database • Container Information - Get detailed metadata including partition key, indexing policy, and throughput settings • Container Statistics - Analyze document count, estimated size, and partition key distribution • Execute SQL Queries - Run custom SQL queries with parameters, result limits, and cross-partition support • Get Documents - Retrieve documents with filtering, partition key specification, and result limiting • Get Document by ID - Fetch specific documents using their unique ID and partition key • Schema Analysis - Examine document structure and data types to identify patterns and anomalies
Allows direct execution from GitHub repository using npx, with configuration instructions for connecting to various MCP clients.
Leverages Node.js runtime for server operations, requiring Node.js 18+ for execution and compatibility.
Built with TypeScript for type safety and modern JavaScript features, providing strongly-typed interfaces for database operations.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP CosmosDBshow me the top 10 products by price from the products container"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP CosmosDB - Azure CosmosDB MCP Server
A comprehensive Model Context Protocol (MCP) server for Azure CosmosDB database operations. This server provides 13 powerful tools for document database analysis, container discovery, data querying, and CRUD operations through the MCP protocol.
✨ Features
🔗 Multi-Connection Support: Manage multiple CosmosDB accounts/databases from a single MCP instance
🔒 Security First: Write operations disabled by default
⚡ High Performance: Connection caching and optimized queries
📊 13 Tools: Complete set of database operations
Related MCP server: MCP Azure DevOps Server
🚀 Quick Start
Prerequisites
Node.js 18+ and npm
Azure CosmosDB database with connection string
MCP-compatible client (Claude Desktop, Cursor IDE, etc.)
⚙️ Configuration
Configuration Priority
The server supports three configuration methods (in order of priority):
Priority | Method | Environment Variable | Description |
1️⃣ | External File |
| Path to JSON file with connections array |
2️⃣ | JSON String |
| Inline JSON array of connections |
3️⃣ | Single Connection |
| Legacy single connection mode |
🔒 Security Configuration
Variable | Description | Default |
| Enable/disable write operations (create, update, delete, upsert) |
|
⚠️ IMPORTANT: By default, all write operations are DISABLED for safety. Set
DB_ALLOW_MODIFICATIONS=trueonly when you need to perform write operations.
📦 Installation Options
Option 1: Multi-Connection with External File (Recommended) ✅
Create a connections file (e.g., cosmos-connections.json):
[
{
"id": "production",
"connectionString": "AccountEndpoint=https://myapp-prod.documents.azure.com:443/;AccountKey=...;",
"databaseId": "ProductionDB",
"allowModifications": false,
"description": "Production database (read-only)"
},
{
"id": "development",
"connectionString": "AccountEndpoint=https://myapp-dev.documents.azure.com:443/;AccountKey=...;",
"databaseId": "DevDB",
"allowModifications": true,
"description": "Development database"
},
{
"id": "analytics",
"connectionString": "AccountEndpoint=https://analytics.documents.azure.com:443/;AccountKey=...;",
"databaseId": "AnalyticsDB",
"allowModifications": false,
"description": "Analytics database"
}
]Configure your MCP client:
{
"mcpServers": {
"cosmosdb": {
"command": "npx",
"args": ["-y", "mcpcosmosdb@latest"],
"env": {
"COSMOS_CONNECTIONS_FILE": "/path/to/cosmos-connections.json"
}
}
}
}Option 2: Multi-Connection with Inline JSON
{
"mcpServers": {
"cosmosdb": {
"command": "npx",
"args": ["-y", "mcpcosmosdb@latest"],
"env": {
"COSMOS_CONNECTIONS": "[{\"id\":\"prod\",\"connectionString\":\"AccountEndpoint=https://...\",\"databaseId\":\"ProdDB\",\"allowModifications\":false},{\"id\":\"dev\",\"connectionString\":\"AccountEndpoint=https://...\",\"databaseId\":\"DevDB\",\"allowModifications\":true}]"
}
}
}
}Option 3: Single Connection (Legacy)
Read-Only Mode (Default - Safe):
{
"mcpServers": {
"cosmosdb": {
"command": "npx",
"args": ["-y", "mcpcosmosdb@latest"],
"env": {
"COSMOS_CONNECTION_STRING": "AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-account-key-here;",
"COSMOS_DATABASE_ID": "your-database-name"
}
}
}
}With Write Operations Enabled:
{
"mcpServers": {
"cosmosdb": {
"command": "npx",
"args": ["-y", "mcpcosmosdb@latest"],
"env": {
"COSMOS_CONNECTION_STRING": "AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-account-key-here;",
"COSMOS_DATABASE_ID": "your-database-name",
"DB_ALLOW_MODIFICATIONS": "true"
}
}
}
}Option 4: NPX from GitHub
{
"mcpServers": {
"cosmosdb": {
"command": "npx",
"args": ["-y", "hendrickcastro/MCPCosmosDB"],
"env": {
"COSMOS_CONNECTION_STRING": "AccountEndpoint=https://...;AccountKey=...;",
"COSMOS_DATABASE_ID": "your-database-name"
}
}
}
}Option 5: Local Development
git clone https://github.com/hendrickcastro/MCPCosmosDB.git
cd MCPCosmosDB
npm install && npm run build{
"mcpServers": {
"cosmosdb": {
"command": "node",
"args": ["path/to/MCPCosmosDB/dist/server.js"],
"env": {
"COSMOS_CONNECTIONS_FILE": "/path/to/cosmos-connections.json"
}
}
}
}🛠️ Available Tools (13 Total)
🔗 Connection Management
Tool | Description |
| List all configured connections with their status |
📖 Read Operations (Always Available)
Tool | Description |
| List all databases in the CosmosDB account |
| List all containers in the current database |
| Get detailed container configuration (partition key, indexing policy, throughput) |
| Get container statistics (document count, size, partition distribution) |
| Execute SQL queries with parameters and performance metrics |
| Retrieve documents with optional filtering |
| Get a specific document by ID and partition key |
| Analyze document schema structure in containers |
✏️ Write Operations (Require allowModifications: true)
Tool | Description |
| Create a new document in a container |
| Update (replace) an existing document |
| Delete a document from a container |
| Create or update a document (upsert operation) |
🛡️ Security Note: Write operations are blocked by default. Set
allowModifications: truein the connection config orDB_ALLOW_MODIFICATIONS=truefor single connection mode.
📋 Usage Examples
Multi-Connection Usage
// List all available connections
const connections = await mcp_list_connections();
// Returns: { connections: [{id: "prod", databaseId: "ProdDB", isConnected: true}, ...] }
// Query specific connection using connection_id
const prodData = await mcp_cosmos_query({
connection_id: "production",
container_id: "users",
query: "SELECT TOP 10 c.id, c.name FROM c ORDER BY c._ts DESC"
});
const devData = await mcp_cosmos_query({
connection_id: "development",
container_id: "users",
query: "SELECT TOP 10 c.id, c.name FROM c ORDER BY c._ts DESC"
});Container Analysis
// List all containers (uses default connection if connection_id not specified)
const containers = await mcp_list_containers({
connection_id: "production"
});
// Get container definition
const containerDef = await mcp_get_container_definition({
connection_id: "production",
container_id: "users"
});
// Get container statistics
const stats = await mcp_get_container_stats({
connection_id: "production",
container_id: "users",
sample_size: 1000
});Querying Data
⚠️ IMPORTANT: Always use TOP N and specify fields. NEVER use - it causes timeouts and high RU consumption in large containers.
// ✅ CORRECT: Using TOP and specific fields
const result = await mcp_cosmos_query({
connection_id: "production",
container_id: "products",
query: "SELECT TOP 50 c.id, c.name, c.price FROM c WHERE c.category = @category",
parameters: { category: "electronics" }
});
// ❌ WRONG: SELECT * without TOP (will timeout on large containers)
// query: "SELECT * FROM c WHERE c.category = @category"
// Get documents with simple filters
const documents = await mcp_get_documents({
connection_id: "production",
container_id: "orders",
filter_conditions: { status: "completed" },
order_by: "_ts",
order_direction: "DESC",
limit: 100
});Document Operations
// Get specific document by ID
const document = await mcp_get_document_by_id({
connection_id: "production",
container_id: "users",
document_id: "user-123",
partition_key: "user-123"
});
// Analyze schema
const schema = await mcp_analyze_schema({
connection_id: "production",
container_id: "products",
sample_size: 500
});CRUD Operations (Requires allowModifications: true)
// Create a new document
const created = await mcp_create_document({
connection_id: "development", // Use a connection with write access
container_id: "users",
document: {
id: "user-456",
email: "user@example.com",
name: "John Doe",
status: "active"
},
partition_key: "user-456"
});
// Update a document (full replacement)
const updated = await mcp_update_document({
connection_id: "development",
container_id: "users",
document_id: "user-456",
document: {
id: "user-456",
email: "newemail@example.com",
name: "John Doe",
status: "inactive"
},
partition_key: "user-456"
});
// Upsert a document (create or update)
const upserted = await mcp_upsert_document({
connection_id: "development",
container_id: "users",
document: {
id: "user-789",
email: "another@example.com",
name: "Jane Doe"
},
partition_key: "user-789"
});
// Delete a document
const deleted = await mcp_delete_document({
connection_id: "development",
container_id: "users",
document_id: "user-456",
partition_key: "user-456"
});🔧 Connection File Schema
interface ConnectionConfig {
id: string; // Unique identifier for the connection
connectionString: string; // CosmosDB connection string
databaseId: string; // Database ID to connect to
allowModifications?: boolean; // Enable write operations (default: false)
description?: string; // Optional description
}Example
[
{
"id": "athlete",
"connectionString": "AccountEndpoint=https://dbsqlcosmosathlete.documents.azure.com:443/;AccountKey=...;",
"databaseId": "data",
"allowModifications": false,
"description": "Athlete data"
},
{
"id": "events",
"connectionString": "AccountEndpoint=https://dbsqlcosmosevents.documents.azure.com:443/;AccountKey=...;",
"databaseId": "events",
"allowModifications": false,
"description": "Events data"
}
]🚨 Troubleshooting
Connection Issues:
Invalid connection string: Verify connection string format includes AccountEndpoint and AccountKey
Database not found: Check databaseId matches existing database
Request timeout: Increase COSMOS_MAX_RETRY_WAIT_TIME or check network
Query Issues:
Query timeout: Use
TOP Nto limit results, specify only needed fields, avoidSELECT *Cross partition query required: Set
enable_cross_partition: truein query parametersPartition key required: Specify partition_key for single-partition operations
Multi-Connection Issues:
Connection not found: Use
mcp_list_connectionsto see available connection IDsWrong database: Verify the
connection_idparameter points to the correct connection
Write Operation Blocked:
Error: "Database modifications are disabled": Set
allowModifications: truein connection config orDB_ALLOW_MODIFICATIONS=trueThis is a safety feature - write operations are disabled by default
CosmosDB Emulator:
Install Azure CosmosDB Emulator
Start emulator on port 8081
Use default emulator connection string
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 & CRUD
│ └── types.ts # Type definitions
├── db.ts # CosmosDB connection & multi-connection management
├── server.ts # MCP server setup
└── tools.ts # Tool definitionsKey Features:
⚡ Connection caching and pooling
🔗 Multi-connection management
🛡️ Comprehensive error handling
🔒 Write operation protection per connection
📊 Performance metrics and request charges
🔧 Flexible configuration options
📋 Intelligent schema analysis
📝 Important Notes
Query Best Practices: Always use
TOP Nand specify fields - never useSELECT *Container IDs: Use exact names as in CosmosDB
Partition Keys: Required for optimal performance and CRUD operations
Cross-Partition Queries: Can be expensive; use filters
Request Charges: Monitor RU consumption
Security: Store connection strings securely (use external file)
Write Protection: Enable only for connections that need it
🤝 Contributing
Fork the repository
Create feature branch (
git checkout -b feature/name)Make changes and add tests
Ensure tests pass (
npm test)Commit changes (
git commit -m 'Add feature')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 multi-database
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 crud-operations document-crud multi-connection
Use Cases: database-development data-science business-intelligence database-migration schema-documentation performance-analysis data-governance database-monitoring troubleshooting automation
🙏 Acknowledgments
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! 🚀