Azure Cosmos DB MCP server

This Node.js-based MCP (Model Context Protocol) server connects to Azure Cosmos DB, providing an interface for AI applications to retrieve product and order data. It acts as a backend component for applications that need to access structured data from Cosmos DB through the MCP protocol.

Installation Requirements

Prerequisites

You'll need to have the following installed:

• Node.js v22.13.1 (LTS) or later
• Azure Cosmos DB NoSQL account
• Azure Storage account
• Azure AD app registration (for authentication)

Setting Up Azure Resources

Create Azure Cosmos DB Account

1. Create a new Azure Cosmos DB for NoSQL account in the Azure portal

2. Enable vector search support:

   • Go to Settings → Features → "Vector Search for NoSQL API"
   • Click the Enable button

3. Create the necessary containers:

   • Create a database named "eshop"
   • Create a "products" container (partition key: "/id")
   • Create a "carts" container (partition key: "/id")
   • Create an "orders" container (partition key: "/id")
   • Configure vector embedding policies for each container

Configure Azure AD Authentication

1. Create an app registration in Azure AD
2. Generate a client secret
3. Assign the necessary RBAC roles:

$SubscriptionId = "<subscription-id>"
$AccountName = "<cosmosdb-account-name>"
$ResourceGroupName = "<resource-group-name>"
$PrincipalId = "<principal-id>"

# Run set_rbac.ps1 script to configure proper permissions

MCP Server Installation

1. Clone the repository:

git clone https://github.com/patrice-truong/cosmosdb-mcp.git
cd cosmosdb-mcp

2. Install dependencies:

cd mcp-server
npm install --legacy-peer-deps

3. Configure environment variables by creating a .env file:

AZURE_COSMOSDB_NOSQL_ENDPOINT=https://<cosmosdb_account>.documents.azure.com:443/
AZURE_COSMOSDB_NOSQL_DATABASE=eshop
AZURE_COSMOSDB_NOSQL_PRODUCTS_CONTAINER=products
AZURE_COSMOSDB_NOSQL_CARTS_CONTAINER=carts
AZURE_COSMOSDB_NOSQL_ORDERS_CONTAINER=orders

NEXT_PUBLIC_AZURE_TENANT_ID=<tenant_id>
NEXT_PUBLIC_AZURE_CLIENT_ID=<client_id>
NEXT_PUBLIC_AZURE_CLIENT_SECRET=<client_secret>

NEXT_PUBLIC_AZURE_STORAGE_ACCOUNT_NAME=<storage_account_name>
NEXT_PUBLIC_AZURE_STORAGE_CONTAINER_NAME=img

AZURE_OPENAI_ENDPOINT=https://<azure_openai_account>.openai.azure.com/
AZURE_OPENAI_API_KEY=<azure_openai_key>
AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
AZURE_OPENAI_API_VERSION=2024-05-01-preview

Usage

Starting the MCP Server

1. Start the MCP server:

cd mcp-server
npx ts-node src/server.ts

The server will start listening for MCP connections.

Populating the Database

Before using the server, you need to populate your Cosmos DB with sample data:

1. Navigate to the populate folder:

cd populate

2. Update the appsettings.json file with your Cosmos DB credentials:

{
  "CosmosDb": {
    "Endpoint": "https://<cosmosdb_account_name>.documents.azure.com:443/",
    "TenantId": "<tenant_id>",
    "DatabaseName": "eshop",
    "ProductsContainerName": "products",
    "OrdersContainerName": "orders"
  }
}

3. Run the population script:

dotnet run

This will populate your database with sample products from the catalog.json file.

Using the MCP Inspector

For debugging and testing your MCP server, you can use the MCP Inspector:

npx -y @modelcontextprotocol/inspector

This tool helps you verify that your MCP server is correctly handling requests and returning the expected data.

Integrating with Client Applications

To connect a client application to your MCP server:

1. The client application should implement the MCP client protocol
2. Configure the client to connect to the MCP server's URL
3. Use the appropriate operations to query products, orders, or other data

Example Queries

Once the server is running, clients can make MCP requests to:

• Find products by category
• Search products with specific attributes
• Retrieve order history for a user
• Get detailed information about specific products

The server handles these requests by querying the Cosmos DB and returning the results formatted according to the MCP protocol.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.