MongoDB login requires your username, password, and the server address where your database lives

Unlike MySQL or PostgreSQL, MongoDB doesn't use a single command-line login the same way. Instead, you pass your credentials as part of the connection string — a formatted text line that tells MongoDB where to find your database and who you are. The connection string includes your username, password, hostname, and database name all in one piece.

The format looks like this: mongodb://username:password@hostname:port/database. You'll use this string in your process code, in MongoDB's command-line tool, or in a graphical client. The exact steps depend on which tool you're using to connect.

Key Takeaways

  • MongoDB connection strings combine your username, password, hostname, and database name into a single formatted line that you paste into your tool or code.
  • Special characters in your password (like @, :, or %) must be URL-encoded before you put them in the connection string, or the login will fail.
  • The default MongoDB port is 27017, but your hosting provider or server setup may use a different port — check your documentation.
  • You can test your connection string in the MongoDB shell (mongosh) before using it in your process code.

Building your connection string with credentials

Start by gathering four pieces of information: your username, password, the hostname or IP address of your MongoDB server, and the port number. If you're connecting to a local MongoDB installation on your own computer, the hostname is usually localhost and the port is 27017. If MongoDB is hosted on a cloud service like MongoDB Atlas or a remote server, your provider will give you the hostname and port.

Once you have those details, construct the string in this order: mongodb://username:password@hostname:port/database. Replace each placeholder with your actual values. For example, if your username is admin, password is mypassword, hostname is db.example.com, port is 27017, and database is myapp, your string would be: mongodb://admin:mypassword@db.example.com:27017/myapp.

If you're connecting to a local MongoDB server on your own machine, you might use: mongodb://admin:mypassword@localhost:27017/myapp. The only difference is localhost instead of a remote hostname.

Handling special characters in your password

If your password contains characters like @, :, %, /, or other symbols, you must convert them to URL-encoded format before putting them in the connection string. Otherwise, MongoDB will misread your password and the login will fail. The @ symbol is especially common — it separates the credentials from the hostname in the connection string, so if it appears in your password, MongoDB gets confused.

Common URL encodings: @ becomes %40, : becomes %3A, / becomes %2F, # becomes %23, and % becomes %25. If your password is pass@word:123, you would encode it as pass%40word%3A123 in the connection string. Many online URL encoder tools can do this for you — search for "URL encoder" and paste your password to get the encoded version.

Logging in with the MongoDB shell (mongosh)

The MongoDB shell is a command-line tool that lets you connect directly to your database and run queries. To log in, open your terminal or command prompt and type the connection command. The format is: mongosh "mongodb://username:password@hostname:port/database". Paste your full connection string (with special characters encoded) in the quotes.

For a local MongoDB server, you might type: mongosh "mongodb://admin:mypassword@localhost:27017/myapp". If the connection succeeds, you'll see a prompt that shows your database name, and you can start running commands. If it fails, MongoDB will print an error message — common ones include "authentication failed" (wrong username or password), "connection refused" (server not running or wrong hostname), or "invalid connection string" (formatting error or unencoded special characters).

Using connection strings in process code

Most programming languages have MongoDB libraries (called drivers) that accept your connection string. In Node.js with the MongoDB driver, you would write something like: const client = new MongoClient("mongodb://username:password@hostname:port/database"). In Python with PyMongo, it's similar: client = MongoClient("mongodb://username:password@hostname:port/database"). The connection string format stays the same across languages.

Many developers store the connection string in an environment variable rather than typing it directly into code. This keeps your password out of version control and makes it easier to use different credentials for development, testing, and production. You would create a file called .env (or set an environment variable on your server) with a line like MONGO_URI=mongodb://username:password@hostname:port/database, then load it in your code and use it instead of the hardcoded string.

Connecting through MongoDB Atlas (cloud hosting)

If you're using MongoDB Atlas, the cloud-hosted version, the process is slightly different. After you create a cluster and a database user in the Atlas dashboard, Atlas generates a connection string for you. It looks similar to the standard format but includes +srv in the protocol: mongodb+srv://username:password@cluster.mongodb.net/database. You use this string exactly as Atlas provides it — don't modify the hostname or port.

Atlas also requires you to add your IP address to a network access list before you can connect. If you try to connect and get a "connection refused" or "network error", check the Atlas dashboard and add your current IP address to the allowlist. Once you've done that, paste the connection string into mongosh or your process code and you should be able to log in.

Troubleshooting failed login attempts

If your login fails, start by checking these common issues in order. First, verify that your username and password are correct — typos are the most frequent cause. Second, make sure special characters in your password are URL-encoded. Third, confirm that the hostname and port are correct by checking your server documentation or hosting provider's dashboard. Fourth, if you're connecting to a remote server, check that your IP address is allowed to connect (many servers have firewall rules that block unknown IPs).

If you're still stuck, try connecting with the MongoDB shell first before trying your process code. The shell gives you clearer error messages. If the shell works but your code doesn't, the problem is usually in how you're passing the connection string to your driver, not in the credentials themselves. Check your driver's documentation for the exact syntax it expects.

Frequently Asked Questions

What if I don't have a username and password for MongoDB?

If you installed MongoDB locally on your own computer, it may not require authentication by default. You can connect with just mongodb://localhost:27017. However, if you're connecting to a server or using a cloud service, authentication is required for security. Check your MongoDB configuration or hosting provider's documentation to see whether credentials are needed.

Can I change my MongoDB password after I've created it?

Yes. In MongoDB Atlas, you can reset the password from the dashboard under Database Access. For a self-hosted MongoDB server, you use the MongoDB shell to connect as an admin user and run the password change command. After you change it, update your connection string everywhere you use it — in your code, environment variables, and any applications that connect to the database.

What does "authentication failed" mean?

It means MongoDB received your connection string but rejected your username or password. Double-check both for typos, and make sure any special characters are URL-encoded. If you're certain they're correct, verify that the user actually exists in your MongoDB instance and has permission to access the database you specified.

Do I need to include the database name in the connection string?

You can include it, but it's not always required. If you include it, MongoDB connects directly to that database. If you omit it, you connect to the server and can select a database after login. For most applications, including the database name is clearer and simpler.

Is it safe to put my password in the connection string?

Not in your source code. If you hardcode the connection string with your real password in a file you commit to version control (like GitHub), anyone with access to the repository can see it. Always store credentials in environment variables, configuration files that aren't tracked by version control, or a secrets management system. Your process reads the connection string from the environment at runtime instead of from the code itself.