Azure Cosmos DB MCP Server

What is this? 🤔

This is a server that lets your LLMs (like Claude) talk directly to your Azure Cosmos DB data! Think of it as a friendly translator that sits between your AI assistant and your database, making sure they can chat securely and efficiently.

Quick Example

You: "What were our top 10 customers last month?"
Claude: *queries your Azure Cosmos DB database and gives you the answer in plain English*

How Does It Work? 🛠️

This server leverages the Model Context Protocol (MCP), a versatile framework that acts as a universal translator between AI models and databases. Although MCP is built to support any AI model, it is currently accessible as a developer preview in Claude Desktop.

Here's all you need to do:

1. Set up project (see below)
2. Add your project details to Claude Desktop's config file
3. Start chatting with your Azure Cosmos DB data naturally!

What Can It Do? 📊

• Run Azure Cosmos DB queries by just asking questions in plain English

Quick Start 🚀

Prerequisites

• Node.js 14 or higher
• Azure Cosmos DB NOSQL account or Azure Cosmos DB Emulator
• Claude Desktop

Configure Claude Desktop

Open Claude Desktop and navigate to File → Settings → Developer → Edit Config to open the claude_desktop_config file.

Add the following configuration with your Azure Cosmos DB credentials:

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["@evkhromov/cosmosdb-mcp@latest"],
      "env": {
        "COSMOSDB_URI": "https://your-account.documents.azure.com:443/",
        "COSMOSDB_KEY": "your-cosmos-db-primary-key",
        "COSMOSDB_DATABASE": "your-database-name"
      }
    }
  }
}

Notes:

• The package is automatically downloaded and run via npx - no installation required
• Container names are dynamically specified by the AI agent when making operations
• You only need to configure the database name in the environment variables
• The @latest tag ensures you always use the most recent version

You should now have successfully configured the MCP server for Azure Cosmos DB with Claude Desktop. This setup allows you to seamlessly interact with Azure Cosmos DB through the MCP server as shown below.

https://github.com/user-attachments/assets/ae3a14f3-9ca1-415d-8645-1c8367fd6943

Using with n8n

This MCP server can be integrated with n8n workflows to enable AI agents to interact with your Azure Cosmos DB data.

Configuration for n8n

1. Configure environment variables in n8n:

   Set the following environment variables in your n8n instance (via .env file or system environment):

   COSMOSDB_URI=https://your-account.documents.azure.com:443/
   COSMOSDB_KEY=your-cosmos-db-primary-key
   COSMOSDB_DATABASE=your-database-name

2. Use in n8n AI Agent node:

   In your n8n workflow, add an AI Agent node and configure it to use the MCP server with npx:

   npx @evkhromov/cosmosdb-mcp@latest

Example n8n Workflow Use Cases

Use Case 1: Data Retrieval Assistant

• User asks: "What documents do we have in the compliant-documents container?"
• AI agent uses MCP to query the container
• Returns structured data to the user

Use Case 2: Automated Data Processing

• Webhook triggers workflow with new data
• AI agent analyzes the data
• Uses MCP to store results in appropriate Cosmos DB container

Use Case 3: Compliance Document Search

• User provides search criteria
• AI agent queries multiple containers via MCP
• Aggregates and returns relevant compliance documents

Available MCP Tools in n8n

The AI agent in n8n can use these tools:

• query_container - Query a container using SQL-like syntax
• get_item - Retrieve a specific item by ID
• put_item - Insert or replace an item
• update_item - Update specific attributes of an item

Example n8n Configuration

{
  "nodes": [
    {
      "type": "n8n-nodes-base.aiAgent",
      "parameters": {
        "mcpServers": [
          {
            "command": "npx",
            "args": ["@ev.khromov/cosmosdb-mcp@latest"]
          }
        ]
      }
    }
  ]
}

Note: Container names are specified dynamically by the AI agent based on the user's query, so you only need to configure the database name in the environment variables.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.