Connect to Azure Cosmos DB for MongoDB (vCore) using MongoDB Shell

2025-10-15

APPLIES TO: MongoDB vCore

MongoDB Shell (mongosh) is a JavaScript and Node.js environment for interacting with MongoDB deployments. It's a popular community tool to test queries and interact with the data in your Azure Cosmos DB for MongoDB (vCore) cluster. This article explains how to connect to an Azure Cosmos DB for MongoDB (vCore) cluster using MongoDB Shell.

Prerequisites

An existing Azure Cosmos DB for MongoDB (vCore) cluster.
MongoDB Shell. For more information, see install MongoDB shell
Firewall rules that allow your client to connect to the cluster. For more information, see configure firewall.

Get cluster credentials

Get the connection string you need to connect to this cluster.

Sign in to the Azure portal (https://portal.azure.cn).
Navigate to the Azure Cosmos DB for MongoDB (vCore) cluster.
Select the Connection strings navigation menu option.
Copy or record the value from the Connection string field.

Important

The connection string in the portal doesn't include the password value. You must replace the <password> placeholder with the credentials you entered when you created the cluster or enter the password interactively.

Connect with interactive password authentication

Connect to your cluster by using the MongoDB Shell with a connection string that doesn't include a password. Use the interactive password prompt to enter your password as part of the connection steps.

Open a terminal.

Connect by entering the password in the MongoDB Shell prompt. For this step, use a connection string without the password.

mongosh "mongodb+srv://<username>@<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000"

After you provide the password and are successfully authenticated, observe the warning that appears
```
This server or service appears to be an emulation of MongoDB.
```
Tip

You can safely ignore this warning. This warning is generated because the connection string contains cosmos.azure. Azure Cosmos DB for MongoDB (vCore) is a native Azure platform as a service (PaaS) offering.
Exit the shell context.

Connect with connection string and password

Now, connect to your cluster from the MongoDB Shell with a connection string and parameters that includes a password.

Connect by using a connection string and the --username and --password arguments.

mongosh "mongodb+srv://<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000" --username "<username>" -password "<password>"

After you provide the password and are successfully authenticated, observe the warning that appears
```
------
   Warning: Non-Genuine MongoDB Detected
   This server or service appears to be an emulation of MongoDB rather than an official MongoDB product.
------
```
Tip

You can safely ignore this warning. This warning is generated because the connection string contains cosmos.azure. Azure Cosmos DB for MongoDB (vCore) is a native Azure platform as a service (PaaS) offering.

Perform test queries

Verify that you're successfully connected to your cluster by performing a series of test commands and queries.

Check your connection status by running the connectionStatus command.
```
db.runCommand({connectionStatus: 1})
```
List the databases in your cluster.
```
show dbs
```
Switch to a specific database. Replace the <database-name> placeholder with the name of any database in your cluster.
```
use <database-name>
```
Tip

For example, if the database name is inventory, then the command would be use inventory.
List the collections within the database.
```
show collections
```
Find the first five items within a specific collection. Replace the <collection-name> placeholder with the name of any collection in your cluster.
```
db.<collection-name>.find().limit(5)
```
Tip

For example, if the collection name is equipment, then the command would be db.equipment.find().limit(5).