Docs Menu
Docs Home
/ / /
Node.js Driver
/ /

Enable SOCKS5 Proxy Support

On this page

  • Overview
  • Install the socks Package
  • SOCKS5 Client Options
  • Example
  • Additional Information
  • API Documentation

In this guide, you can learn how to connect to MongoDB instances by using a SOCKS5 proxy. SOCKS5 is a standardized protocol for connecting to network services through a proxy server.


To learn more about the SOCKS5 protocol, see the Wikipedia entry on SOCKS.

Starting in version 6.0 of the Node.js driver, you must install the socks package to use SOCKS5 proxy support in your application. You can install socks by running the following command in your shell:

npm i socks

You can set options in your MongoClientOptions instance or in your connection URI to configure SOCKS5 proxy support for your connection. The following table describes the client options related to SOCKS5:

Accepted Values
Default Value
Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or domain name.
non-negative integer
Specifies the TCP port number of the SOCKS5 proxy server. If you set the proxyHost option, the value of this option defaults to 1080.
Specifies the username for authentication to the SOCKS5 proxy server. If you set this option to a zero-length string, the driver ignores it.
Specifies the password for authentication to the SOCKS5 proxy server. If you set this option to a zero-length string, the driver ignores it.


The driver throws an error if you set the proxyPort, proxyUsername, or proxyPassword options without setting the proxyHost option.

This example shows how to instantiate a MongoClient that uses SOCKS5 proxy support. The following example code specifies proxy server options and connects to MongoDB:

// Replace the placeholder with your connection string
const uri = "<connection string uri>";
// Replace the placeholders with your SOCKS5 proxy server details
const socksOptions = {
proxyHost: "<host>",
proxyPort: 1080,
proxyUsername: "<username>",
proxyPassword: "<password>",
// Create a new client with the proxy server details
const client = new MongoClient(uri, socksOptions);


The preceding sample code uses placeholders for the connection URI and proxy server details. To run this code, you must replace these placeholders with the information for your deployment and proxy server.

For more information about SOCKS5 proxy support, see the MongoDB SOCKS5 specification.

To learn more about the methods and types discussed in this guide, see the following API Documentation:

← Enable TLS on a Connection