Connect to MongoDB over an SSH tunnel

Why use an SSH tunnel?

MongoDB typically listens on port 27017. In production you rarely want that port reachable from the public internet. Instead, you place MongoDB on a private subnet accessible only from a bastion (jump) host that accepts SSH on port 22. Your local client then connects to the bastion over SSH, and the bastion forwards traffic to MongoDB — the database never sees a direct connection from your laptop.

The result is encrypted transit (SSH) without having to open firewall rules or expose MongoDB's port to the world.

What you need before you start

• The bastion host address (hostname or IP) and its SSH port (usually 22).
• A username on the bastion (for example, ubuntu or ec2-user).
• Either an SSH private key (RSA, Ed25519, ECDSA — passphrase-protected keys are supported) or a password for the bastion user.
• The MongoDB host and port as seen from the bastion — often localhost:27017 if MongoDB runs on the same machine, or a private DNS name like mongo-primary.internal:27017.

Setting up the connection in MQLens

Open MQLens and click New Connection. Fill in the MongoDB host and port using the address that is reachable from the bastion, not from your laptop. For example, if MongoDB runs on the same EC2 instance as your bastion, use localhost and port 27017.

Scroll down to the SSH Tunnel section and toggle it on. You will see the following fields:

• SSH Host / Port — the public address of your bastion and its SSH port.
• SSH Username — the username on the bastion server.
• Authentication method — choose Private Key to browse for a .pem or .key file, or choose Password to type it inline (stored in your encrypted local vault).
• Private key passphrase — if your key is passphrase-protected, enter it here; MQLens never stores it in plaintext.

Add your MongoDB credentials (username, password, auth database) in theAuthentication section as usual. TLS settings also work in combination with SSH tunneling — you can run TLS over the tunnel if your server requires it.

Using the staged Test Connection to debug

Before saving, click Test Connection. MQLens runs the connection in distinct, named phases and reports the outcome of each one:

• Parse checks the connection URI.
• Resolve checks the database hostname for direct connections. With SSH enabled, the database hostname is resolved through the remote host, so this local check is skipped.
• Connect opens the SSH tunnel. Check the bastion address, port, SSH credentials, and firewall rules if it fails.
• Ping checks MongoDB through the tunnel. Errors can indicate a database address, TLS, or authentication problem; use the reported error to narrow it down.

Some authentication methods also show a sign-in step. Once the test succeeds, save the connection. MQLens will re-establish the SSH tunnel when you reconnect.

SOCKS5 proxy as an alternative

If your team uses a SOCKS5 proxy (for example, established withssh -D 1080 user@bastion), MQLens supports that too. Switch the proxy type to SOCKS5, point it at127.0.0.1:1080, and leave the SSH tunnel fields empty. Use Test Connection to check the resulting connection.