Azure Cosmos MCP Samples
This repository contains a collection of sample implementations of the MCP across multiple programming languages, all backed by Azure Cosmos DB. These examples demonstrate how to create, query, update, and delete documents using the Azure Cosmos DB S
What is Azure Cosmos MCP Samples?
Azure Cosmos MCP Samples is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to this repository contains a collection of sample implementations of the mcp across multiple programming languages, all backed by azure cosmos db. these examples demonstrate how to create, query, update...
This repository contains a collection of sample implementations of the MCP across multiple programming languages, all backed by Azure Cosmos DB. These examples demonstrate how to create, query, update, and delete documents using the Azure Cosmos DB S
This server falls under the Cloud Services and Databases categories on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- This repository contains a collection of sample implementati
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx azure-cosmos-mcp-server-samplesConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Azure Cosmos MCP Samples
Azure Cosmos DB MCP Server Samples is a multi-language reference repository that demonstrates how to build MCP servers backed by Azure Cosmos DB, covering JavaScript, Go, Java, and Python implementations. Each sample shows AI agents how to perform document CRUD operations, run natural language queries, execute vector searches, and discover schemas against a Cosmos DB backend using Azure Entra ID for secure authentication. Teams use these samples as starting points for building production MCP integrations with Azure's globally distributed NoSQL database.
Prerequisites
- An active Azure subscription with an Azure Cosmos DB account (NoSQL API)
- Azure CLI installed and authenticated (`az login`) for Entra ID access
- Runtime for your chosen language: Node.js 18+ for JavaScript, Go 1.21+ for GoLang, JDK 17+ for Java, or Python 3.10+ for Python
- An MCP-compatible client such as Claude Desktop
- Git to clone the repository
Clone the repository
Clone the Azure Cosmos DB MCP Server Samples repository to your local machine and navigate into it.
git clone https://github.com/AzureCosmosDB/azure-cosmos-mcp-server-samples.git
cd azure-cosmos-mcp-server-samplesChoose your language implementation
Navigate to the directory for your preferred language. Each subdirectory contains a self-contained MCP server implementation with its own setup instructions.
# Choose one:
cd javascript
# or: cd golang
# or: cd java
# or: cd pythonSet up Azure Cosmos DB credentials
Configure your Azure Cosmos DB connection details. You will need your Cosmos DB endpoint URL and either an account key or Azure Entra ID credentials. For Entra ID, ensure your identity has the Cosmos DB Built-in Data Contributor role.
export COSMOS_ENDPOINT="https://your-account.documents.azure.com:443/"
export COSMOS_KEY="your_primary_key_here"
export COSMOS_DATABASE="your_database_name"Install dependencies and build
Follow the language-specific setup. For the JavaScript implementation, install npm packages and build the project.
# JavaScript example:
npm install
npm run buildConfigure your MCP client
Add the built server to your Claude Desktop configuration file. Adjust the command and args for your chosen language implementation.
Azure Cosmos MCP Samples Examples
Client configuration
Claude Desktop configuration for the JavaScript sample implementation of the Azure Cosmos DB MCP server.
{
"mcpServers": {
"azure-cosmos": {
"command": "node",
"args": ["/path/to/azure-cosmos-mcp-server-samples/javascript/dist/index.js"],
"env": {
"COSMOS_ENDPOINT": "https://your-account.documents.azure.com:443/",
"COSMOS_KEY": "your_primary_key_here",
"COSMOS_DATABASE": "your_database_name"
}
}
}
}Prompts to try
Use these prompts to interact with your Azure Cosmos DB database through the MCP server.
- "List all containers in my Cosmos DB database"
- "Create a new document in the products container with name 'Widget' and price 29.99"
- "Query all orders where status is 'pending'"
- "Find documents in the catalog container similar to 'blue running shoes' using vector search"
- "What is the schema structure of the customers container?"
- "Delete the document with id 'abc-123' from the inventory container"Troubleshooting Azure Cosmos MCP Samples
Authentication error: Forbidden or 401 from Cosmos DB
Verify your COSMOS_ENDPOINT and COSMOS_KEY are correct. For Entra ID authentication, run `az login` and ensure your identity has the 'Cosmos DB Built-in Data Contributor' role assigned on the Cosmos DB account.
Build fails in the Go or Java implementation
Ensure you have the correct runtime version installed (Go 1.21+ or JDK 17+). For Java, use `mvn clean package` rather than a direct build command. Each language folder contains a language-specific README with exact build steps.
Vector search queries return no results
Vector search requires a container configured with a vector index policy in Cosmos DB. Ensure your container has vector indexing enabled and that documents have been inserted with embedding vectors in the expected field.
Frequently Asked Questions about Azure Cosmos MCP Samples
What is Azure Cosmos MCP Samples?
Azure Cosmos MCP Samples is a Model Context Protocol (MCP) server that this repository contains a collection of sample implementations of the mcp across multiple programming languages, all backed by azure cosmos db. these examples demonstrate how to create, query, update, and delete documents using the azure cosmos db s It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Azure Cosmos MCP Samples?
Follow the installation instructions on the Azure Cosmos MCP Samples GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Azure Cosmos MCP Samples?
Azure Cosmos MCP Samples works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Azure Cosmos MCP Samples free to use?
Yes, Azure Cosmos MCP Samples is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Azure Cosmos MCP Samples Alternatives — Similar Cloud Services Servers
Looking for alternatives to Azure Cosmos MCP Samples? Here are other popular cloud services servers you can use with Claude, Cursor, and VS Code.
Open WebUI
★ 138.2kUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)
Anything LLM
★ 60.4kThe all-in-one AI productivity accelerator. On device and privacy first with no annoying setup or configuration.
LocalAI
★ 46.4kLocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.
Nacos
★ 33.0kan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.
Xiaozhi ESP32
★ 26.7k本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.
Gateway
★ 11.8kA blazing fast AI Gateway with integrated guardrails. Route to 1,600+ LLMs, 50+ AI Guardrails with 1 fast & friendly API.
Browse More Cloud Services MCP Servers
Explore all cloud services servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Azure Cosmos MCP Samples in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Azure Cosmos MCP Samples?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.