MongoDB MCP Server

A Model Context Protocol server for interacting with MongoDB Databases and MongoDB Atlas.

📚 Table of Contents

🚀 Getting Started
- Prerequisites
- Setup
  - Quick Start
🛠️ Supported Tools
- MongoDB Atlas Tools
- MongoDB Database Tools
📄 Supported Resources
⚙️ Configuration
🚀 Deploy on Public Clouds
- Azure Cloud
🤝 Contributing

Prerequisites

Node.js
- At least 20.19.0
- When using v22 then at least v22.12.0
- Otherwise any version 23+

node -v

A MongoDB connection string or Atlas API credentials, the Server will not start unless configured.
- Service Accounts Atlas API credentials are required to use the Atlas tools. You can create a service account in MongoDB Atlas and use its credentials for authentication. See Atlas API Access for more details.
- If you have a MongoDB connection string, you can use it directly to connect to your MongoDB instance.

Setup

Quick Start

🔒 Security Recommendation 1: When using Atlas API credentials, be sure to assign only the minimum required permissions to your service account. See Atlas API Permissions for details.

🔒 Security Recommendation 2: For enhanced security, we strongly recommend using environment variables to pass sensitive configuration such as connection strings and API credentials instead of command line arguments. Command line arguments can be visible in process lists and logged in various system locations, potentially exposing your secrets. Environment variables provide a more secure way to handle sensitive information.

Most MCP clients require a configuration file to be created or modified to add the MCP server.

Note: The configuration file syntax can be different across clients. Please refer to the following links for the latest expected syntax:

Windsurf: https://docs.windsurf.com/windsurf/mcp
VSCode: https://code.visualstudio.com/docs/copilot/chat/mcp-servers
Claude Desktop: https://modelcontextprotocol.io/quickstart/user
Cursor: https://docs.cursor.com/context/model-context-protocol

Default Safety Notice: All examples below include --readOnly by default to ensure safe, read-only access to your data. Remove --readOnly if you need to enable write operations.

Option 1: Connection String

You can pass your connection string via environment variables, make sure to use a valid username and password.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
      }
    }
  }
}

NOTE: The connection string can be configured to connect to any MongoDB cluster, whether it's a local instance or an Atlas cluster.

Option 2: Atlas API Credentials

Use your Atlas API Service Accounts credentials. Must follow all the steps in Atlas API Access section.

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

Option 3: Standalone Service using environment variables and command line arguments

You can source environment variables defined in a config file or explicitly set them like we do in the example below and run the server via npx.

# Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Then start the server
npx -y mongodb-mcp-server@latest --readOnly

💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.

For a complete list of configuration options see Configuration Options
To configure your Atlas Service Accounts credentials please refer to Atlas API Access
Connection String via environment variables in the MCP file example
Atlas API credentials via environment variables in the MCP file example

Option 4: Using Docker

You can run the MongoDB MCP Server in a Docker container, which provides isolation and doesn't require a local Node.js installation.

Run with Environment Variables

You may provide either a MongoDB connection string OR Atlas API credentials:

Option A: No configuration

docker run --rm -i \
  mongodb/mongodb-mcp-server:latest

Option B: With MongoDB connection string

# Set your credentials as environment variables first
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# Then start the docker container
docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING \
  -e MDB_MCP_READ_ONLY="true" \
  mongodb/mongodb-mcp-server:latest

💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.

Option C: With Atlas API credentials

# Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Then start the docker container
docker run --rm -i \
  -e MDB_MCP_API_CLIENT_ID \
  -e MDB_MCP_API_CLIENT_SECRET \
  -e MDB_MCP_READ_ONLY="true" \
  mongodb/mongodb-mcp-server:latest

💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.

Docker in MCP Configuration File

Without options:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "-i",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

With connection string:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_CONNECTION_STRING",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "mongodb/mongodb-mcp-server:latest"
      ],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}

With Atlas API credentials:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "-e",
        "MDB_MCP_API_CLIENT_ID",
        "-e",
        "MDB_MCP_API_CLIENT_SECRET",
        "mongodb/mongodb-mcp-server:latest"
      ],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

Option 5: Running as an HTTP Server

⚠️ Security Notice: This server now supports Streamable HTTP transport for remote connections. HTTP transport is NOT recommended for production use without implementing proper authentication and security measures.

Suggested Security Measures Examples:

Implement authentication (e.g., API gateway, reverse proxy)
Use HTTPS/TLS encryption
Deploy behind a firewall or in private networks
Implement rate limiting
Never expose directly to the internet

For more details, see MCP Security Best Practices.

You can run the MongoDB MCP Server as an HTTP server instead of the default stdio transport. This is useful if you want to interact with the server over HTTP, for example from a web client or to expose the server on a specific port.

To start the server with HTTP transport, use the --transport http option:

npx -y mongodb-mcp-server@latest --transport http

By default, the server will listen on http://127.0.0.1:3000. You can customize the host and port using the --httpHost and --httpPort options:

npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --httpPort=8080

--httpHost (default: 127.0.0.1): The host to bind the HTTP server.
--httpPort (default: 3000): The port number for the HTTP server.

Note: The default transport is stdio, which is suitable for integration with most MCP clients. Use http transport if you need to interact with the server over HTTP.

🛠️ Supported Tools

Tool List

MongoDB Atlas Tools

atlas-connect-cluster - Connect to MongoDB Atlas cluster
atlas-create-access-list - Allow Ip/CIDR ranges to access your MongoDB Atlas clusters.
atlas-create-db-user - Create an MongoDB Atlas database user
atlas-create-free-cluster - Create a free MongoDB Atlas cluster
atlas-create-project - Create a MongoDB Atlas project
atlas-get-performance-advisor - Get MongoDB Atlas performance advisor recommendations, which includes the operations: suggested indexes, drop index suggestions, schema suggestions, and a sample of the most recent (max 50) slow query logs
atlas-inspect-access-list - Inspect Ip/CIDR ranges with access to your MongoDB Atlas clusters.
atlas-inspect-cluster - Inspect MongoDB Atlas cluster
atlas-list-alerts - List MongoDB Atlas alerts
atlas-list-clusters - List MongoDB Atlas clusters
atlas-list-db-users - List MongoDB Atlas database users
atlas-list-orgs - List MongoDB Atlas organizations
atlas-list-projects - List MongoDB Atlas projects

NOTE: atlas tools are only available when you set credentials on configuration section.

MongoDB Atlas Local Tools

atlas-local-connect-deployment - Connect to a MongoDB Atlas Local deployment
atlas-local-create-deployment - Create a MongoDB Atlas local deployment
atlas-local-delete-deployment - Delete a MongoDB Atlas local deployment
atlas-local-list-deployments - List MongoDB Atlas local deployments

MongoDB Database Tools

aggregate - Run an aggregation against a MongoDB collection
collection-indexes - Describe the indexes for a collection
collection-schema - Describe the schema for a collection
collection-storage-size - Gets the size of the collection
connect - Connect to a MongoDB instance
count - Gets the number of documents in a MongoDB collection using db.collection.count() and query as an optional filter parameter
create-collection - Creates a new collection in a database. If the database doesn't exist, it will be created automatically.
create-index - Create an index for a collection
db-stats - Returns statistics that reflect the use state of a single database
delete-many - Removes all documents that match the filter from a MongoDB collection
drop-collection - Removes a collection or view from the database. The method also removes any indexes associated with the dropped collection.
drop-database - Removes the specified database, deleting the associated data files
drop-index - Drop an index for the provided database and collection.
explain - Returns statistics describing the execution of the winning plan chosen by the query optimizer for the evaluated method
export - Export a query or aggregation results in the specified EJSON format.
find - Run a find query against a MongoDB collection
insert-many - Insert an array of documents into a MongoDB collection
list-collections - List all collections for a given database
list-databases - List all databases for a MongoDB connection
mongodb-logs - Returns the most recent logged mongod events
rename-collection - Renames a collection in a MongoDB database
switch-connection - Switch to a different MongoDB connection
update-many - Updates all documents that match the specified filter for a collection

📄 Supported Resources

config - Server configuration, supplied by the user either as environment variables or as startup arguments with sensitive parameters redacted. The resource can be accessed under URI config://config.
debug - Debugging information for MongoDB connectivity issues. Tracks the last connectivity attempt and error information. The resource can be accessed under URI debug://mongodb.
exported-data - A resource template to access the data exported using the export tool. The template can be accessed under URI exported-data://{exportName} where exportName is the unique name for an export generated by the export tool.

Configuration

🔒 Security Best Practice: We strongly recommend using environment variables for sensitive configuration such as API credentials (MDB_MCP_API_CLIENT_ID, MDB_MCP_API_CLIENT_SECRET) and connection strings (MDB_MCP_CONNECTION_STRING) instead of command-line arguments. Environment variables are not visible in process lists and provide better security for your sensitive data.

The MongoDB MCP Server can be configured using multiple methods, with the following precedence (highest to lowest):

Command-line arguments
Environment variables
Configuration File

Configuration Options

Environment Variable / CLI Option	Default	Description
`MDB_MCP_ALLOW_REQUEST_OVERRIDES` / `--allowRequestOverrides`	`false`	When set to true, allows configuration values to be overridden via request headers and query parameters.
`MDB_MCP_API_CLIENT_ID` / `--apiClientId`	`<not set>`	Atlas API client ID for authentication. Required for running Atlas tools.
`MDB_MCP_API_CLIENT_SECRET` / `--apiClientSecret`	`<not set>`	Atlas API client secret for authentication. Required for running Atlas tools.
`MDB_MCP_ATLAS_TEMPORARY_DATABASE_USER_LIFETIME_MS` / `--atlasTemporaryDatabaseUserLifetimeMs`	`14400000`	Time in milliseconds that temporary database users created when connecting to MongoDB Atlas clusters will remain active before being automatically deleted.
`MDB_MCP_CONFIRMATION_REQUIRED_TOOLS` / `--confirmationRequiredTools`	`"atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many,drop-index"`	Comma separated values of tool names that require user confirmation before execution. Requires the client to support elicitation.
`MDB_MCP_CONNECTION_STRING` / `--connectionString`	`<not set>`	MongoDB connection string for direct database connections. Optional, if not set, you'll need to call the connect tool before interacting with MongoDB data.
`MDB_MCP_DISABLED_TOOLS` / `--disabledTools`	`""`	Comma separated values of tool names, operation types, and/or categories of tools that will be disabled.
`MDB_MCP_DRY_RUN` / `--dryRun`	`false`	When true, runs the server in dry mode: dumps configuration and enabled tools, then exits without starting the server.
`MDB_MCP_EMBEDDINGS_VALIDATION` / `--embeddingsValidation`	`true`	When set to false, disables validation of embeddings dimensions.
`MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS` / `--exportCleanupIntervalMs`	`120000`	Time in milliseconds between export cleanup cycles that remove expired export files.
`MDB_MCP_EXPORT_TIMEOUT_MS` / `--exportTimeoutMs`	`300000`	Time in milliseconds after which an export is considered expired and eligible for cleanup.
`MDB_MCP_EXPORTS_PATH` / `--exportsPath`	see below*	Folder to store exported data files.
`MDB_MCP_HTTP_HEADERS` / `--httpHeaders`	`"{}"`	Header that the HTTP server will validate when making requests (only used when transport is 'http').
`MDB_MCP_HTTP_HOST` / `--httpHost`	`"127.0.0.1"`	Host address to bind the HTTP server to (only used when transport is 'http').
`MDB_MCP_HTTP_PORT` / `--httpPort`	`3000`	Port number for the HTTP server (only used when transport is 'http'). Use 0 for a random port.
`MDB_MCP_IDLE_TIMEOUT_MS` / `--idleTimeoutMs`	`600000`	Idle timeout for a client to disconnect (only applies to http transport).
`MDB_MCP_INDEX_CHECK` / `--indexCheck`	`false`	When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan.
`MDB_MCP_LOG_PATH` / `--logPath`	see below*	Folder to store logs.
`MDB_MCP_LOGGERS` / `--loggers`	`"disk,mcp"` see below*	Comma separated values of logger types.
`MDB_MCP_MAX_BYTES_PER_QUERY` / `--maxBytesPerQuery`	`16777216`	The maximum size in bytes for results from a find or aggregate tool call. This serves as an upper bound for the responseBytesLimit parameter in those tools.
`MDB_MCP_MAX_DOCUMENTS_PER_QUERY` / `--maxDocumentsPerQuery`	`100`	The maximum number of documents that can be returned by a find or aggregate tool call. For the find tool, the effective limit will be the smaller of this value and the tool's limit parameter.
`MDB_MCP_NOTIFICATION_TIMEOUT_MS` / `--notificationTimeoutMs`	`540000`	Notification timeout for a client to be aware of disconnect (only applies to http transport).
`MDB_MCP_PREVIEW_FEATURES` / `--previewFeatures`	`""`	Comma separated values of preview features that are enabled.
`MDB_MCP_READ_ONLY` / `--readOnly`	`false`	When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations.
`MDB_MCP_TELEMETRY` / `--telemetry`	`"enabled"`	When set to disabled, disables telemetry collection.
`MDB_MCP_TRANSPORT` / `--transport`	`"stdio"`	Either 'stdio' or 'http'.
`MDB_MCP_VECTOR_SEARCH_DIMENSIONS` / `--vectorSearchDimensions`	`1024`	Default number of dimensions for vector search embeddings.
`MDB_MCP_VECTOR_SEARCH_SIMILARITY_FUNCTION` / `--vectorSearchSimilarityFunction`	`"euclidean"`	Default similarity function for vector search: 'euclidean', 'cosine', or 'dotProduct'.
`MDB_MCP_VOYAGE_API_KEY` / `--voyageApiKey`	`""`	API key for Voyage AI embeddings service (required for vector search operations with text-to-embedding conversion).

Logger Options

The loggers configuration option controls where logs are sent. You can specify one or more logger types as a comma-separated list. The available options are:

mcp: Sends logs to the MCP client (if supported by the client/transport).
disk: Writes logs to disk files. Log files are stored in the log path (see logPath above).
stderr: Outputs logs to standard error (stderr), useful for debugging or when running in containers.

Default: disk,mcp (logs are written to disk and sent to the MCP client).

You can combine multiple loggers, e.g. --loggers disk stderr or export MDB_MCP_LOGGERS="mcp,stderr".

Example: Set logger via environment variable

export MDB_MCP_LOGGERS="disk,stderr"

💡 Platform Note: For Windows users, see Environment Variables for platform-specific instructions.

Example: Set logger via command-line argument

npx -y mongodb-mcp-server@latest --loggers mcp stderr

Log File Location

When using the disk logger, log files are stored in:

Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs
macOS/Linux: ~/.mongodb/mongodb-mcp/.app-logs

You can override the log directory with the logPath option.

🔒 Security Guideline: The user account running the MCP server must have both read and write permissions to the logPath directory. Ensure this directory is properly secured with appropriate file system permissions to prevent unauthorized access to log files.

Disabled Tools

You can disable specific tools or categories of tools by using the disabledTools option. This option accepts an array of strings, where each string can be a tool name, operation type, or category.

The way the array is constructed depends on the type of configuration method you use:

For environment variable configuration, use a comma-separated string: export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema".
For command-line argument configuration, use a space-separated string: --disabledTools create update delete atlas collectionSchema.

Categories of tools:

atlas - MongoDB Atlas tools, such as list clusters, create cluster, etc.
mongodb - MongoDB database tools, such as find, aggregate, etc.

Operation types:

create - Tools that create resources, such as create cluster, insert document, etc.
update - Tools that update resources, such as update document, rename collection, etc.
delete - Tools that delete resources, such as delete document, drop collection, etc.
read - Tools that read resources, such as find, aggregate, list clusters, etc.
metadata - Tools that read metadata, such as list databases/collections/indexes, infer collection schema, etc.
connect - Tools that allow you to connect or switch the connection to a MongoDB instance. If this is disabled, you will need to provide a connection string through the config when starting the server.

Require Confirmation

If your client supports elicitation, you can set the MongoDB MCP server to request user confirmation before executing certain tools.

When a tool is marked as requiring confirmation, the server will send an elicitation request to the client. The client with elicitation support will then prompt the user for confirmation and send the response back to the server. If the client does not support elicitation, the tool will execute without confirmation.

You can set the confirmationRequiredTools configuration option to specify the names of tools which require confirmation. By default, the following tools have this setting enabled: drop-database, drop-collection, delete-many, atlas-create-db-user, atlas-create-access-list.

Read-Only Mode

The readOnly configuration option allows you to restrict the MCP server to only use tools with "read", "connect", and "metadata" operation types. When enabled, all tools that have "create", "update" or "delete" operation types will not be registered with the server.

This is useful for scenarios where you want to provide access to MongoDB data for analysis without allowing any modifications to the data or infrastructure.

You can enable read-only mode using:

Environment variable: export MDB_MCP_READ_ONLY=true
Command-line argument: --readOnly

💡 Platform Note: For Windows users, see Environment Variables for platform-specific instructions.

When read-only mode is active, you'll see a message in the server logs indicating which tools were prevented from registering due to this restriction.

Index Check Mode

The indexCheck configuration option allows you to enforce that query operations must use an index. When enabled, queries that perform a collection scan will be rejected to ensure better performance.

This is useful for scenarios where you want to ensure that database queries are optimized.

You can enable index check mode using:

Environment variable: export MDB_MCP_INDEX_CHECK=true
Command-line argument: --indexCheck

💡 Platform Note: For Windows users, see Environment Variables for platform-specific instructions.

When index check mode is active, you'll see an error message if a query is rejected due to not using an index.

Exports

The data exported by the export tool is temporarily stored in the configured exportsPath on the machine running the MCP server until cleaned up by the export cleanup process. If the exportsPath configuration is not provided, the following defaults are used:

Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\exports
macOS/Linux: ~/.mongodb/mongodb-mcp/exports

The exportTimeoutMs configuration controls the time after which the exported data is considered expired and eligible for cleanup. By default, exports expire after 5 minutes (300000ms).

The exportCleanupIntervalMs configuration controls how frequently the cleanup process runs to remove expired export files. By default, cleanup runs every 2 minutes (120000ms).

🔒 Security Guideline: The user account running the MCP server must have both read and write permissions to the exportsPath directory. Ensure this directory is properly secured with appropriate file system permissions to prevent unauthorized access to exported data files, which may contain sensitive MongoDB data. Consider the sensitivity of your data when choosing the export location and apply restrictive permissions accordingly.

Telemetry

The telemetry configuration option allows you to disable telemetry collection. When enabled, the MCP server will collect usage data and send it to MongoDB.

You can disable telemetry using:

Environment variable: export MDB_MCP_TELEMETRY=disabled
Command-line argument: --telemetry disabled
DO_NOT_TRACK environment variable: export DO_NOT_TRACK=1

💡 Platform Note: For Windows users, see Environment Variables for platform-specific instructions.

Opting into Preview Features

The MongoDB MCP Server may offer functionality that is still in development and may change in future releases. These features are considered "preview features" and are not enabled by default. Generally, these features are well tested, but may not offer the complete functionality we intend to provide in the final release or we'd like to gather feedback before making them generally available. To enable one or more preview features, use the previewFeatures configuration option.

For environment variable configuration, use a comma-separated string: export MDB_MCP_PREVIEW_FEATURES="search,feature1,feature2".
For command-line argument configuration, use a space-separated string: --previewFeatures search feature1 feature2.

List of available preview features:

search - Enables tools or functionality related to Atlas Search and Vector Search in MongoDB Atlas:
- Index management, such as creating, listing, and dropping search and vector search indexes.
- Querying collections using vector search capabilities. This requires a configured embedding model that will be used to generate vector representations of the query data. Currently, only Voyage AI embedding models are supported. Set the voyageApiKey configuration option with your Voyage AI API key to use this feature.

Atlas API Access

To use the Atlas API tools, you'll need to create a service account in MongoDB Atlas:

ℹ️ Note: For a detailed breakdown of the minimum required permissions for each Atlas operation, see the Atlas API Permissions section below.

Create a Service Account:
- Log in to MongoDB Atlas at cloud.mongodb.com
- Navigate to Access Manager > Organization Access
- Click Add New > Applications > Service Accounts
- Enter name, description and expiration for your service account (e.g., "MCP, MCP Server Access, 7 days")
- Assign only the minimum permissions needed for your use case.
  - See Atlas API Permissions for details.
- Click "Create"

To learn more about Service Accounts, check the MongoDB Atlas documentation.

Save Client Credentials:
- After creation, you'll be shown the Client ID and Client Secret
- Important: Copy and save the Client Secret immediately as it won't be displayed again
Add Access List Entry:
- Add your IP address to the API access list
Configure the MCP Server:
- Use one of the configuration methods below to set your apiClientId and apiClientSecret

Atlas API Permissions

Security Warning: Granting the Organization Owner role is rarely necessary and can be a security risk. Assign only the minimum permissions needed for your use case.

Quick Reference: Required roles per operation

What you want to do	Safest Role to Assign (where)
List orgs/projects	Org Member or Org Read Only (Org)
Create new projects	Org Project Creator (Org)
View clusters/databases in a project	Project Read Only (Project)
Create/manage clusters in a project	Project Cluster Manager (Project)
Manage project access lists	Project IP Access List Admin (Project)
Manage database users	Project Database Access Admin (Project)

Prefer project-level roles for most operations. Assign only to the specific projects you need to manage or view.
Avoid Organization Owner unless you require full administrative control over all projects and settings in the organization.

For a full list of roles and their privileges, see the Atlas User Roles documentation.

Configuration Methods

Configuration File

Store configuration in a JSON file and load it using the MDB_MCP_CONFIG environment variable.

🔒 Security Best Practice: Prefer using the MDB_MCP_CONFIG environment variable for sensitive fields over the configuration file or --config CLI argument. Command-line arguments are visible in process listings.

🔒 File Security: Ensure your configuration file has proper ownership and permissions, limited to the user running the MongoDB MCP server:

Linux/macOS:
chmod 600 /path/to/config.json
chown your-username /path/to/config.json
Windows: Right-click the file → Properties → Security → Restrict access to your user account only.

Create a JSON file with your configuration (all keys use camelCase):

{
  "connectionString": "mongodb://localhost:27017",
  "readOnly": true,
  "loggers": ["stderr", "mcp"],
  "apiClientId": "your-atlas-service-accounts-client-id",
  "apiClientSecret": "your-atlas-service-accounts-client-secret",
  "maxDocumentsPerQuery": 100
}

Linux/macOS (bash/zsh):

export MDB_MCP_CONFIG="/path/to/config.json"
npx -y mongodb-mcp-server@latest

Windows Command Prompt (cmd):

set "MDB_MCP_CONFIG=C:\path\to\config.json"
npx -y mongodb-mcp-server@latest

Windows PowerShell:

$env:MDB_MCP_CONFIG="C:\path\to\config.json"
npx -y mongodb-mcp-server@latest

Environment Variables

Set environment variables with the prefix MDB_MCP_ followed by the option name in uppercase with underscores:

Linux/macOS (bash/zsh):

# Set Atlas API credentials (via Service Accounts)
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Set a custom MongoDB connection string
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# Set log path
export MDB_MCP_LOG_PATH="/path/to/logs"

Windows Command Prompt (cmd):

set "MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id"
set "MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret"

set "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

set "MDB_MCP_LOG_PATH=C:\path\to\logs"

Windows PowerShell:

# Set Atlas API credentials (via Service Accounts)
$env:MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
$env:MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Set a custom MongoDB connection string
$env:MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# Set log path
$env:MDB_MCP_LOG_PATH="C:\path\to\logs"

MCP configuration file examples

Connection String with environment variables

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}

Atlas API credentials with environment variables

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

Command-Line Arguments

Pass configuration options as command-line arguments when starting the server:

🔒 Security Note: For sensitive configuration like API credentials and connection strings, use environment variables instead of command-line arguments.

# Set sensitive data as environment variable
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# Start the server with command line arguments
npx -y mongodb-mcp-server@latest --logPath=/path/to/logs --readOnly --indexCheck

💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.

MCP configuration file examples

Connection String with command-line arguments

🔒 Security Note: We do not recommend passing connection string as command line argument. Connection string might contain credentials which can be visible in process lists and logged in various system locations, potentially exposing your credentials. Instead configure connection string through environment variables

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
        "--readOnly"
      ]
    }
  }
}

Atlas API credentials with command-line arguments

🔒 Security Note: We do not recommend passing Atlas API credentials as command line argument. The provided credentials can be visible in process lists and logged in various system locations, potentially exposing your credentials. Instead configure Atlas API credentials through environment variables

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

Proxy Support

The MCP Server will detect typical PROXY environment variables and use them for connecting to the Atlas API, your MongoDB Cluster, or any other external calls to third-party services like OID Providers. The behaviour is the same as what mongosh does, so the same settings will work in the MCP Server.

🚀Deploy on Public Clouds

You can deploy the MongoDB MCP Server to your preferred cloud provider using the deployment assets under deploy/. Each guide explains the prerequisites, configuration, and automation scripts that streamline the rollout.

Azure

For detailed Azure instructions, see deploy/azure/README.md.

🤝Contributing

Interested in contributing? Great! Please check our Contributing Guide for guidelines on code contributions, standards, adding new tools, and troubleshooting information.

Features

Rate this server

Features

Rate this server