Mcp Cosmosdb Sql

Name: Mcp Cosmosdb Sql
Author: hendrickcastro

@hendrickcastro

About Mcp Cosmosdb Sql

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.

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

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

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Mcp Cosmosdb Sql?

Mcp Cosmosdb Sql is a comprehensive Model Context Protocol (MCP) server for Azure CosmosDB database operations. It provides eight tools for document database analysis, container discovery, and data querying through the MCP protocol, targeting developers using MCP-compatible clients like Claude Desktop or Cursor IDE.

How to use Mcp Cosmosdb Sql?

Install and configure by adding the server to your MCP client’s JSON configuration (e.g., claude_desktop_config.json) with the command npx -y hendrickcastro/MCPCosmosDB and environment variables OCONNSTRING and COSMOS_DATABASE_ID. Alternatively, clone the repository, run npm install && npm run build, and point the client to dist/server.js. Invoke any of the eight tools via the client’s MCP interface.

Key features of Mcp Cosmosdb Sql

List all databases in the CosmosDB account
List and get detailed information about containers
Execute SQL queries against containers with parameters
Retrieve documents with optional filters and partition key targeting
Retrieve a specific document by ID and partition key
Analyze document schema structure in containers
Performance metrics with query request charges
Automatic connection pooling and retry logic

Use cases of Mcp Cosmosdb Sql

Container analysis: list containers, view index policies, and get statistics
Querying data: run parameterized SQL queries and retrieve filtered documents
Document operations: fetch specific documents by ID and partition key
Schema analysis: understand data patterns and document structures in a container

FAQ from Mcp Cosmosdb Sql

How do I connect to Azure CosmosDB?

Set the OCONNSTRING environment variable to your CosmosDB connection string (including AccountEndpoint and AccountKey) and set COSMOS_DATABASE_ID to your database name.

What tools are available?

Eight tools: mcp_list_databases, mcp_list_containers, mcp_container_info, mcp_container_stats, mcp_execute_query, mcp_get_documents, mcp_get_document_by_id, and mcp_analyze_schema.

What should I do if I get a “Cross partition query required” error?

Set enable_cross_partition: true in your query parameters, or increase the COSMOS_ENABLE_CROSS_PARTITION_QUERY environment variable.

Can I use the CosmosDB Emulator for local development?

Yes. Use the default emulator connection string (AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/…) and ensure the emulator is running on port 8081.