📌Overview

Purpose: The Azure Cosmos DB MCP Server enables seamless communication between AI models and Azure Cosmos DB, facilitating natural language queries for database interactions.

Overview: This server acts as a mediator that allows AI assistants, like Claude, to query Azure Cosmos DB databases using simple English commands. By leveraging the Model Context Protocol (MCP), it transforms traditional database interactions into a conversational experience, enhancing user accessibility to data.

Key Features:

Natural Language Querying: Users can make queries to Azure Cosmos DB in plain English, streamlining the process of retrieving data without needing to know complex query languages.
MCP Integration: Built on the Model Context Protocol framework, the server serves as a universal translator between AI models and databases, allowing flexible support for various AI systems currently in preview.

Azure Cosmos DB MCP Server

What is this? 🤔

This server allows your LLMs (like Claude, VS Code) to communicate directly with your Azure Cosmos DB data. It acts as a translator between your AI assistant and your database, enabling secure and efficient interaction.

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? 🛠️

The server uses the Model Context Protocol (MCP), a framework that acts as a universal translator between AI models and databases. MCP supports any AI model but is currently available as a developer preview in Claude Desktop.

Steps to use:

Set up the project (instructions below)
Add your project details to Claude Desktop's config file
Start querying your Azure Cosmos DB data naturally!

What Can It Do? 📊

Run Azure Cosmos DB queries by asking questions in plain English

Quick Start 🚀

Prerequisites

Node.js 14 or higher
Azure Cosmos DB NoSQL account or Azure Cosmos DB Emulator with sample dataset inserted
Claude Desktop

Set up project

Get your Azure Cosmos DB NoSQL account URI and KEY from the Keys section, and Database ID and Container ID from the Data Explorer. Then create a .env file with the following keys:

COSMOSDB_URI=
COSMOSDB_KEY=
COSMOS_DATABASE_ID=
COSMOS_CONTAINER_ID=

Getting Started

Install Dependencies
Run in the root folder:
```
npm install
```
Build the Project
Compile the project:
```
npm run build
```
Start the Server
Navigate to the dist folder and start the server:
```
npm start
```

Confirmation Message
You should see:

Azure Cosmos DB Server running on stdio

How to run it using VS Code Insiders

To use Azure MCP with VS Code Insiders and GitHub Copilot Agent Mode:

Install VS Code Insiders.
Install pre-release GitHub Copilot and GitHub Copilot Chat extensions in VS Code Insiders.
Open a new instance of VS Code Insiders in an empty folder.
Copy the mcp.json file from this repo to your new folder, and update the values to match your environment.
Open GitHub Copilot and switch to Agent mode. You should see Azure Cosmos DB MCP Server in the list of tools.
Try prompts like "List Vehicles" to interact with the Azure MCP server.

Add your project details to Claude Desktop's config file

Open Claude Desktop and navigate to File -> Settings -> Developer -> Edit Config. Replace with:

{
  "mcpServers": {
    "cosmosdb": {
      "command": "node",
      "args": [ "C:/Cosmos/azure-cosmos-mcp/dist/index.js" ],
      "env": {
        "COSMOSDB_URI": "Your Cosmos DB Account URI",
        "COSMOSDB_KEY": "Your Cosmos DB KEY",
        "COSMOS_DATABASE_ID": "Your Database ID",
        "COSMOS_CONTAINER_ID": "Vehicles"
      }
    }
  }
}

You are now ready to interact with Azure Cosmos DB through the MCP server in Claude Desktop.

Contributing

Contributions and suggestions are welcome. Most contributions require agreeing to a Contributor License Agreement (CLA) to grant rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

A CLA bot will determine if a CLA is needed when you submit a pull request.

This project follows the Microsoft Open Source Code of Conduct. For questions, contact opencode@microsoft.com.

Trademarks

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

azure-cosmos-mcp-server