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

🚀 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	`COSMOS_CONNECTIONS_FILE`	Path to JSON file with connections array
2️⃣	JSON String	`COSMOS_CONNECTIONS`	Inline JSON array of connections
3️⃣	Single Connection	`COSMOS_CONNECTION_STRING` + `COSMOS_DATABASE_ID`	Legacy single connection mode

🔒 Security Configuration

Variable	Description	Default
`DB_ALLOW_MODIFICATIONS`	Enable/disable write operations (create, update, delete, upsert)	`false`

⚠️ IMPORTANT: By default, all write operations are DISABLED for safety. Set DB_ALLOW_MODIFICATIONS=true only 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
`mcp_list_connections`	List all configured connections with their status

📖 Read Operations (Always Available)

Tool	Description
`mcp_list_databases`	List all databases in the CosmosDB account
`mcp_list_containers`	List all containers in the current database
`mcp_get_container_definition`	Get detailed container configuration (partition key, indexing policy, throughput)
`mcp_get_container_stats`	Get container statistics (document count, size, partition distribution)
`mcp_cosmos_query`	Execute SQL queries with parameters and performance metrics
`mcp_get_documents`	Retrieve documents with optional filtering
`mcp_get_document_by_id`	Get a specific document by ID and partition key
`mcp_analyze_schema`	Analyze document schema structure in containers

✏️ Write Operations (Require `allowModifications: true`)

Tool	Description
`mcp_create_document`	Create a new document in a container
`mcp_update_document`	Update (replace) an existing document
`mcp_delete_document`	Delete a document from a container
`mcp_upsert_document`	Create or update a document (upsert operation)

🛡️ Security Note: Write operations are blocked by default. Set allowModifications: true in the connection config or DB_ALLOW_MODIFICATIONS=true for 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 SELECT * - 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 cosmos-connections.json:

[
  {
    "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 N to limit results, specify only needed fields, avoid SELECT *
Cross partition query required: Set enable_cross_partition: true in query parameters
Partition key required: Specify partition_key for single-partition operations

Multi-Connection Issues:

Connection not found: Use mcp_list_connections to see available connection IDs
Wrong database: Verify the connection_id parameter points to the correct connection

Write Operation Blocked:

Error: "Database modifications are disabled": Set allowModifications: true in connection config or DB_ALLOW_MODIFICATIONS=true
This 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 definitions

Key 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 N and specify fields - never use SELECT *
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

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

MCP CosmosDB - Azure CosmosDB MCP Server

✨ 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

🚀 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	`COSMOS_CONNECTIONS_FILE`	Path to JSON file with connections array
2️⃣	JSON String	`COSMOS_CONNECTIONS`	Inline JSON array of connections
3️⃣	Single Connection	`COSMOS_CONNECTION_STRING` + `COSMOS_DATABASE_ID`	Legacy single connection mode

🔒 Security Configuration

Variable	Description	Default
`DB_ALLOW_MODIFICATIONS`	Enable/disable write operations (create, update, delete, upsert)	`false`

⚠️ IMPORTANT: By default, all write operations are DISABLED for safety. Set DB_ALLOW_MODIFICATIONS=true only 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
`mcp_list_connections`	List all configured connections with their status

📖 Read Operations (Always Available)

Tool	Description
`mcp_list_databases`	List all databases in the CosmosDB account
`mcp_list_containers`	List all containers in the current database
`mcp_get_container_definition`	Get detailed container configuration (partition key, indexing policy, throughput)
`mcp_get_container_stats`	Get container statistics (document count, size, partition distribution)
`mcp_cosmos_query`	Execute SQL queries with parameters and performance metrics
`mcp_get_documents`	Retrieve documents with optional filtering
`mcp_get_document_by_id`	Get a specific document by ID and partition key
`mcp_analyze_schema`	Analyze document schema structure in containers

✏️ Write Operations (Require `allowModifications: true`)

Tool	Description
`mcp_create_document`	Create a new document in a container
`mcp_update_document`	Update (replace) an existing document
`mcp_delete_document`	Delete a document from a container
`mcp_upsert_document`	Create or update a document (upsert operation)

🛡️ Security Note: Write operations are blocked by default. Set allowModifications: true in the connection config or DB_ALLOW_MODIFICATIONS=true for 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 SELECT * - 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 cosmos-connections.json:

[
  {
    "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 N to limit results, specify only needed fields, avoid SELECT *
Cross partition query required: Set enable_cross_partition: true in query parameters
Partition key required: Specify partition_key for single-partition operations

Multi-Connection Issues:

Connection not found: Use mcp_list_connections to see available connection IDs
Wrong database: Verify the connection_id parameter points to the correct connection

Write Operation Blocked:

Error: "Database modifications are disabled": Set allowModifications: true in connection config or DB_ALLOW_MODIFICATIONS=true
This 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 definitions

Key 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 N and specify fields - never use SELECT *
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

🙏 Acknowledgments

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

MCP CosmosDB

MCP CosmosDB - Azure CosmosDB MCP Server

✨ Features

🚀 Quick Start

Prerequisites

⚙️ Configuration

Configuration Priority

🔒 Security Configuration

📦 Installation Options

Option 1: Multi-Connection with External File (Recommended) ✅

Option 2: Multi-Connection with Inline JSON

Option 3: Single Connection (Legacy)

Option 4: NPX from GitHub

Option 5: Local Development

🛠️ Available Tools (13 Total)

🔗 Connection Management

📖 Read Operations (Always Available)

✏️ Write Operations (Require allowModifications: true)

📋 Usage Examples

Multi-Connection Usage

Container Analysis

Querying Data

Document Operations

CRUD Operations (Requires allowModifications: true)

🔧 Connection File Schema

🚨 Troubleshooting

🧪 Development

🏗️ Architecture

📝 Important Notes

🤝 Contributing

📄 License

🏷️ Tags & Keywords

🙏 Acknowledgments

MCP CosmosDB - Azure CosmosDB MCP Server

✨ Features

🚀 Quick Start

Prerequisites

⚙️ Configuration

Configuration Priority

🔒 Security Configuration

📦 Installation Options

Option 1: Multi-Connection with External File (Recommended) ✅

Option 2: Multi-Connection with Inline JSON

Option 3: Single Connection (Legacy)

Option 4: NPX from GitHub

Option 5: Local Development

🛠️ Available Tools (13 Total)

🔗 Connection Management

📖 Read Operations (Always Available)

✏️ Write Operations (Require allowModifications: true)

📋 Usage Examples

Multi-Connection Usage

Container Analysis

Querying Data

Document Operations

CRUD Operations (Requires allowModifications: true)

🔧 Connection File Schema

🚨 Troubleshooting

🧪 Development

🏗️ Architecture

📝 Important Notes

🤝 Contributing

📄 License

🏷️ Tags & Keywords

🙏 Acknowledgments

✏️ Write Operations (Require `allowModifications: true`)

CRUD Operations (Requires `allowModifications: true`)

✏️ Write Operations (Require `allowModifications: true`)

CRUD Operations (Requires `allowModifications: true`)