Skip to main content
Glama

MCP CosmosDB

by hendrickcastro
GitHub
TypeScript
MIT License
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP CosmosDB - Azure CosmosDB MCP Server

License: MIT Node.js Version TypeScript GitHub stars GitHub issues GitHub forks Build Status Coverage Status Azure CosmosDB MCP Protocol MCP Protocol Claude Desktop Cursor IDE Trae AI

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

Variable

Description

Example

OCONNSTRING

CosmosDB connection string from Azure Portal

AccountEndpoint=https://...;AccountKey=...;

COSMOS_DATABASE_ID

Database ID to connect to

MyDatabase

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

Variable

Description

Default

COSMOS_ENABLE_ENDPOINT_DISCOVERY

Enable automatic endpoint discovery

true

COSMOS_MAX_RETRY_ATTEMPTS

Maximum retry attempts for requests

9

COSMOS_MAX_RETRY_WAIT_TIME

Maximum retry wait time (ms)

30000

COSMOS_ENABLE_CROSS_PARTITION_QUERY

Enable cross-partition queries

true

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

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

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

A Model Context Protocol server for Azure CosmosDB database operations that provides 8 tools for document database analysis, container discovery, and data querying.

  1. 🚀 Quick Start
    1. Prerequisites
  2. ⚙️ Configuration
    1. Required Environment Variables
    2. Installation Options
  3. 🛠️ Available Tools
    1. 1. 🗄️ List Databases - mcp_list_databases
    2. 2. 📦 List Containers - mcp_list_containers
    3. 3. 📋 Container Information - mcp_container_info
    4. 4. 📊 Container Statistics - mcp_container_stats
    5. 5. 🔍 Execute SQL Query - mcp_execute_query
    6. 6. 📄 Get Documents - mcp_get_documents
    7. 7. 🎯 Get Document by ID - mcp_get_document_by_id
    8. 8. 🏗️ Schema Analysis - mcp_analyze_schema
  4. 📋 Usage Examples
    1. Container Analysis
    2. Querying Data
    3. Document Operations
    4. Optional Configuration
    5. Configuration Examples
  5. 🚨 Troubleshooting
    1. 🧪 Development
      1. 🏗️ Architecture
        1. 📝 Important Notes
          1. 🤝 Contributing
            1. 📄 License
              1. 🏷️ Tags & Keywords
                1. 🙏 Acknowledgments

                  Related MCP Servers

                  • Azure MCP Server

                    mashriram
                    A
                    security
                    A
                    license
                    A
                    quality
                    This server implements the Model Context Protocol for seamless interaction with Azure Blob Storage and Cosmos DB, enabling automatic logging and audit tracking of operations.
                    Last updated -
                    19
                    5
                    MIT License
                    • Apple

                  • MCP Azure DevOps Server

                    Vortiago
                    A
                    security
                    A
                    license
                    A
                    quality
                    A Model Context Protocol server that enables AI assistants to interact with Azure DevOps services, allowing users to query work items with plans to support creating/updating items, managing pipelines, handling pull requests, and administering sprints and branch policies.
                    Last updated -
                    21
                    74
                    MIT License
                    • Linux
                    • Apple

                  • Azure Resource Graph MCP Server

                    hardik-id
                    A
                    security
                    A
                    license
                    A
                    quality
                    A Model Context Protocol server for querying and analyzing Azure resources at scale using Azure Resource Graph, enabling AI assistants to explore and monitor Azure infrastructure.
                    Last updated -
                    1
                    11
                    MIT License
                    • Linux
                    • Apple

                  • Azure DevOps MCP Server

                    jhlia0
                    -
                    security
                    F
                    license
                    -
                    quality
                    A Model Context Protocol server that integrates with Azure DevOps, enabling users to query work items, access backlogs, and perform various Azure DevOps operations through a standardized interface.
                    Last updated -
                    1

                  View all related MCP servers

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/hendrickcastro/MCPCosmosDB'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server