Connect to MongoDB Atlas from your Mac

What you need

• Your Mac’s public IP address on the project’s IP access list. Atlas allows no connections until you add an entry.
• A database user (username and password). Database users are separate from the account you sign in to Atlas with; Atlas creates one with your first cluster.
• A client that supports TLS. The Free (M0) and Flex tiers also need the client to send the server name in the TLS handshake (SNI); mongosh does.

Find your connection details

1. In Atlas, open your project and choose Clusters under the Database heading.
2. Click Connect on the cluster.
3. Choose the connection security: Standard Connection from your Mac (the others are for VPC peering and private endpoints).
4. If asked, click Add Your Current IP Address, and create a database user.
5. Choose Shell for the mongosh command, or a driver for the bare connection string, and copy it.

You can change both later, in the project’s network access and database access settings. An IP access list entry can be temporary, expiring within up to seven days, which suits a laptop on a café network. Password (SCRAM) users authenticate against the admin database.

Connection string

mongodb+srv://<username>:<password>@cluster0.<id>.mongodb.net/

The host is the cluster’s SRV name, ending in .mongodb.net (Atlas’s example is cluster0.dfget.mongodb.net).

The +srv form names the cluster, not its servers. Your client looks up a DNS SRV record to find the hosts, and a TXT record supplies options such as authSource and replicaSet. Because of that you can’t add a port, and +srv turns TLS on by itself.

If your network’s DNS can’t do SRV lookups, toggle off SRV Connection String in the Connect window to get the standard mongodb://host1:27017,host2:27017,… form instead.

Percent-encode these characters, and spaces, in the username or password: : / ? # [ ] @ ! $ & ' ( ) * , ; = %. For example, p@ssw0rd'9'! becomes p%40ssw0rd%279%27%21. More in MongoDB connection strings and special characters in passwords.

TLS

Atlas requires TLS. Its server certificates are signed by Google Trust Services or Let’s Encrypt (both in use at once), so clients must trust the GTS Root R1–R4 and ISRG Root X1 certificates. macOS includes all five (checked on macOS 26.2), so on a Mac there’s no CA file to download. Atlas renews server certificates often (they’re valid for 90 days), which is another reason not to pin one.

Connect with Inlet

1. Copy the mongodb+srv:// string and paste it into Inlet. Inlet fills in the connection form and finds the cluster’s hosts from DNS. Or choose New Connection, pick MongoDB, and enter the details.
2. Leave TLS on. With a +srv string it’s on already, and the certificate is checked against the certificates macOS trusts.
3. Save the password in the Keychain, or have Inlet ask every time.
4. Tag the environment. A connection tagged production opens read-only until you unlock it, for ten minutes at a time.

For production, it’s also worth signing in as a database user whose only role is readAnyDatabase, MongoDB’s built-in read-only role for every database (apart from local and config). Then the server itself refuses writes, whatever the client does.

In Inlet, collections appear as tables and documents open in the inspector; queries use mongosh syntax, such as db.users.find({ email: "a@example.com" }).

Connect from the command line

Under Shell in the Connect window, Atlas gives you a mongosh command with the connection string and your user name; run it and mongosh asks for the password. It has this form:

mongosh "mongodb+srv://cluster0.<id>.mongodb.net/" --username <username>

Change --username to connect as a different database user.

Homebrew has mongosh (brew install mongosh). Check the SRV record your client depends on:

dig SRV _mongodb._tcp.cluster0.<id>.mongodb.net

And that the database port is open from your network:

nc -zv <node-hostname> 27017

Troubleshooting

• A timeout or server selection error: first check your current IP is on the IP access list (it changes when you move networks), and add it if not. A paused cluster also can’t be reached; Atlas pauses idle Free (M0) clusters after 30 days with no connections.
• Authentication failed: check the database user’s name and password (not your Atlas login), that you’re connecting to the right cluster, and the authSource. Percent-encode special characters in the password.
• querySrv ECONNREFUSED _mongodb._tcp… or DNSHostNotFound: your DNS server can’t answer SRV lookups. Switch to a public DNS server, or use the standard (non-SRV) string.
• Refused even with the right IP: a firewall may block outbound port 27017 (sharded clusters also need 27016).
• connection refused because too many open connections: the limit depends on the cluster tier. Close unused connections or move to a larger tier.