Mcpcosmosdb

🚀 MCP CosmosDB - Azure CosmosDB MCP Server

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

🚀 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)

✨ Features

• Offers 8 comprehensive tools for Azure CosmosDB operations, including database listing, container analysis, and SQL query execution.
• Manages connections with retry logic for stability.
• Implements comprehensive error handling.
• Provides performance metrics and request charges.
• Supports environment-based configuration.
• Conducts intelligent schema analysis.

📦 Installation

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

💻 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

⚠️ Important Note

Connection Issues:

• Invalid connection string: Verify that the OCONNSTRING format includes AccountEndpoint and AccountKey.
• Database not found: Check that the 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 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 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 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

Important Notes

💡 Usage Tip

• 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 for request charges.
• 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 tests pass (npm test).
5. Commit 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. Perfect for developers and data analysts working with CosmosDB! 🚀