Azure Cosmos DB MCP CLient & Server

@patrice-truong

About Azure Cosmos DB MCP CLient & Server

Azure Cosmos DB MCP Client and Server

Config

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

{
  "mcpServers": {
    "cosmosdb-mcp": {
      "command": "npx",
      "args": [
        "ts-node",
        "src/server.ts"
      ]
    }
  }
}

Tools

No tools detected

Fetch the live tool list by running this server in a temporary sandbox using the button above.

Overview

What is Azure Cosmos DB MCP Client & Server?

This project demonstrates how to build an MCP Server and client connected to Azure Cosmos DB for NoSQL. It includes a NextJS 15 frontend that displays a product catalog and provides an AI Assistant for searching products and retrieving past orders, alongside a Node.js MCP Server that reads products and orders from the database.

How to use Azure Cosmos DB MCP Client & Server?

Clone the repository, configure environment variables (Azure Cosmos DB endpoint, database, containers, Azure Storage, Azure OpenAI credentials), then start the MCP server with npx ts-node src/server.ts from the mcp-server folder. Run the frontend with npm start from the nextjs folder. Optionally, populate the product catalog using the provided .NET tool in the populate folder.

Key features of Azure Cosmos DB MCP Client & Server

MCP Server connected to Azure Cosmos DB NoSQL
NextJS 15 frontend with product catalog display
AI Assistant for product search and order lookup
Vector search enabled on Cosmos DB for semantic queries
Integration with Azure Blob Storage for product images
Uses Azure OpenAI for embedding generation

Use cases of Azure Cosmos DB MCP Client & Server

Build an AI-powered e-commerce store with natural language product search
Enable customers to retrieve their order history through a chat interface
Demonstrate MCP integration with Azure Cosmos DB for real-time data access

FAQ from Azure Cosmos DB MCP Client & Server

What Azure services are required?

Azure Cosmos DB for NoSQL (with vector search enabled), Azure Blob Storage for images, and Azure OpenAI for embeddings.

How do I populate the product catalog?

Run the .NET console application in the populate folder after configuring appsettings.json with your Cosmos DB account details and after authenticating with Azure (az login).

Where does data live?

Product, cart, and order data is stored in Azure Cosmos DB containers. Product images are hosted in Azure Blob Storage.

What authentication is used?

The project uses Azure RBAC (role-based access control) with an app registration and client secret. It also requires a storage account role assignment (Storage Blob Data Contributor). No built-in user authentication is implemented; the user email is hardcoded in nextjs/models/constants.ts.

How do I run the MCP Inspector?

Optionally start the MCP inspector with npx -y @modelcontextprotocol/inspector after the MCP server is running.

Frequently asked questions

What Azure services are required?

Azure Cosmos DB for NoSQL (with vector search enabled), Azure Blob Storage for images, and Azure OpenAI for embeddings.

How do I populate the product catalog?

Run the .NET console application in the `populate` folder after configuring `appsettings.json` with your Cosmos DB account details and after authenticating with Azure (az login).