MongoDB MCP Server Configuration

The MongoDB MCP Server is currently in Public Preview.

You must configure the MCP Server to connect an AI client to the cluster. You can then use an AI client to perform cluster operations.

This page describes AI client compatibility, how to configure the MCP Server, troubleshooting, and disabling MCP Server tools and telemetry.

AI Client Compatibility

The MCP Server is compatible with many AI clients that support MCP. For example, you can use these AI clients:

The JSON configuration file structure can vary for each AI client. Read the AI client documentation for details.

Prerequisites

The MCP Server can run Atlas tools that perform various Atlas operations. To run the Atlas tools, your Atlas cluster requires a service account with the appropriate permissions.

To set up a service account, see MongoDB MCP Server Prerequisites.

For a list of the tools, see MongoDB MCP Server Tools.

MCP Server Configuration Options

The MCP Server has various options that you can set to connect to a cluster and control MCP Server operations. You can set the options in a JSON configuration file, on a command line, or in operating system environment variables.

The following table shows the MCP Server configuration options:

Option	Type	Description
`apiClientId`	string	Atlas API client ID for authentication.
`apiClientSecret`	string	Atlas API client secret for authentication.
`connectionString`	string	Connection string for a direct database connection. Sets the connection string at runtime to allow the client to directly connect to a cluster. Note Typically, avoid providing the connection string at runtime because you expose the connection credentials to the large language model. The connection string is used if the client has never connected before, or the client switches the connection to a new cluster if the client was previously connected. After the client calls the connect or switch connection tool, the client reuses the same connection for subsequent operations. Therefore, you only need to call the connect or swtich connection tool once or if you need to switch to a different connection.
`logPath`	string	Directory that stores the MCP Server logs.
`disabledTools`	array	An array of MCP tool names, operation types, or tool categories to disable.
`readOnly`	boolean	If `true`, the MCP Server allows only read and metadata operation types, and disables create, update, and delete operations. Default is `false`.
`telemetry`	string	If `disabled`, MCP Server usage data collection is stopped. Default is `enabled`.

MCP Server Configuration Methods

To configure the MCP Server, use any of these methods:

JSON configuration file with MCP Server options
Command line options
Operating system environment variables

The MCP Server uses Atlas API credentials or a connection string to access a cluster.

MCP Server Cluster Connection Methods and Options

To configure the MCP Server to connect to a cluster and set other MCP Server options, use a method described in this section.

Connecting with Atlas API Credentials

You can use the Atlas API credentials obtained in MongoDB MCP Server Prerequisites to connect to an Atlas cluster.

Note

As you'll see in the next section, you can also connect to an Atlas cluster using a MongoDB connection string if you don't want to use Atlas API credentials for security or another reason.

To connect with Atlas API credentials, set the apiClientId and apiClientSecret options in the JSON configuration file for the AI client:

{
 "mcpServers": {
 "MongoDB": {
 "command": "npx",
 "args": [
 "-y", "mongodb-mcp-server",
 "--apiClientId", "<atlas-service-accounts-client-id>",
 "--apiClientSecret", "<atlas-service-accounts-client-secret>"
 ]
 }
 }
}

Connecting with Cluster Connection String

If you don't want to use Atlas API credentials for security or another reason, you can connect to a cluster using a MongoDB connection string.

The following example shows a connectionString to connect to an Atlas cluster:

{
 "mcpServers": {
 "MongoDB": {
 "command": "npx",
 "args": [
 "-y", "mongodb-mcp-server",
 "--connectionString",
 "mongodb+srv://testUser:testPassword@testCluster.mongodb.net/"
 ]
 }
 }
}

You can also connect to a local cluster with a connection string. For example:

{
 "mcpServers": {
 "MongoDB": {
 "command": "npx",
 "args": [
 "-y", "mongodb-mcp-server",
 "--connectionString",
 "mongodb://127.0.0.1:27019/?directConnection=true"
 ]
 }
 }
}

Defining MCP Server Environment Variables

You can define environment variables to set various configuration options for the MCP Server.

To define operating system environment variables for the MCP Server, use the prefix MDB_MCP_ followed by the variable name in uppercase with underscores. For example, use MDB_MCP_CONNECTION_STRING to set the connectionString option.

For a list of options, see MCP Server Configuration Options.

Defining Environment Variables in Operating System

The following examples show how to define MCP Server environment variables in a Unix-based operating system:

# Set Atlas API credentials for a service account
export MDB_MCP_API_CLIENT_ID="<atlas-service-accounts-client-id>"
export MDB_MCP_API_CLIENT_SECRET="<atlas-service-accounts-client-secret>"
# Set a MongoDB connection string
export MDB_MCP_CONNECTION_STRING="mongodb+srv://testUsername:testPassword@testCluster.mongodb.net/testDatabase"
# Change the MCP Server log path from the default
export MDB_MCP_LOG_PATH="/mcp/logs"

The following examples set the same variables using in a Windows command line:

:: Set Atlas API credentials for a service account
set MDB_MCP_API_CLIENT_ID=<atlas-service-accounts-client-id>
set MDB_MCP_API_CLIENT_SECRET=<atlas-service-accounts-client-secret>
:: Set a MongoDB connection string
set MDB_MCP_CONNECTION_STRING="mongodb+srv://testUsername::testPassword@testCluster.mongodb.net/testDatabase"
:: Change the MCP Server log path from the default
set MDB_MCP_LOG_PATH="C:\mcp\logs"

The following examples set the same variables in a Windows PowerShell session:

# Set Atlas API credentials for a service account
$env:MDB_MCP_API_CLIENT_ID="<atlas-service-accounts-client-id>"
$env:MDB_MCP_API_CLIENT_SECRET="<atlas-service-accounts-client-secret>"
# Set a MongoDB connection string
$env:MDB_MCP_CONNECTION_STRING="mongodb+srv://testUsername::testPassword@testCluster.mongodb.net/testDatabase"
# Change the MCP Server log path from the default
$env:MDB_MCP_LOG_PATH="C:\mcp\logs"

Defining Connection String Environment Variable in Configuration File

The following example shows how to define the connection string environment variable in a JSON configuration file:

{
 "mcpServers": {
 "MongoDB": {
 "command": "npx",
 "args": ["-y", "mongodb-mcp-server"],
 "env": {
 "MDB_MCP_CONNECTION_STRING":
 "mongodb+srv://testUsername:testPassword@testCluster.mongodb.net/testDatabase"
 }
 }
 }
}

Defining Atlas API Environment Variables in Configuration File

The following example shows how to define Atlas API environment variables in a JSON configuration file:

{
 "mcpServers": {
 "MongoDB": {
 "command": "npx",
 "args": ["-y", "mongodb-mcp-server"],
 "env": {
 "MDB_MCP_API_CLIENT_ID": "<atlas-service-accounts-client-id>",
 "MDB_MCP_API_CLIENT_SECRET": "<atlas-service-accounts-client-secret>"
 }
 }
 }
}

Enabling MCP Server Read-Only Mode

You can limit the MCP Server to perform only read operations using read-only mode.

To enable read-only mode with a command line option, use:

--readOnly

To enable read-only mode using an environment variable, set the MDB_MCP_READ_ONLY environment variable to true:

export MDB_MCP_READ_ONLY=true

When you enable read-only mode, a message is added to the MCP Server log that indicates the tools that perform write operations are prevented from running.

Troubleshooting MCP Server

If you have issues with the MCP Server, examine the log files for information that can help you troubleshoot the problem.

The following table shows the default directories where the MCP Server stores the log files:

Operating System	Default Log Directory
Windows	`%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs`
macOS and Linux	`~/.mongodb/mongodb-mcp/.app-logs`

You can change the log path if required. To do that, set one of these:

logPath option in a JSON configuration file or command line
MDB_MCP_LOG_PATH environment variable

Disabling MCP Server Tools

To restrict access to Atlas and database operations, you can disable specific MCP Server tools or categories of tools.

To disable tools, set the disabledTools MCP Server configuration option, which is an array of strings. Each string can be a tool name or tool category.

The following table shows the tool names that you can disable:

Tool Name	Description	Example Operations Disabled
`create`	Create resources	Create cluster Insert document
`update`	Update resources	Update document Rename collection
`delete`	Delete resources	Delete document Drop collection
`read`	Read resources	Find Aggregate List clusters
`metadata`	Read metadata	List databases List collections Read collection schema

The following table shows the tool categories that you can disable:

Tool Category	Description	Example Operations Disabled
`atlas`	Atlas tools	List clusters Create cluster
`mongodb`	Database tools	Find Aggregate

To disable tools with the disabledTools command line option, use a space-separated list. For example:

--disabledTools create update delete atlas

To disable tools with the MDB_MCP_DISABLED_TOOLS environment variable, use a comma-separated string. For example:

export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas"

Disabling MCP Server Telemetry

To prevent the MCP Server from collecting data about usage, you can disable telemetry.

To disable telemetry using an environment variable, set either of these:

export MDB_MCP_TELEMETRY=disabled
export DO_NOT_TRACK=1

To disable telemetry using a command line option, use:

--telemetry disabled

Learn More

Back

Prerequisites

Tools