Atlas MCP Server

A Model Context Protocol server for interacting with MongoDB Atlas. This project implements a Model Context Protocol (MCP) server enabling AI assistants to interact with MongoDB Atlas resources through natural language.

Caution

Do not use this in production. This is a work in progress and is not intended for production use. It is meant for demonstration purposes only.

📚 Table of Contents

• 🚀 Getting Started
  • Prerequisites
  • Installation
    • VSCode
    • Claude Desktop
• 🛠️ Supported Tools
  • Tool List
• ⚙️ Configuration
  • Configuration Options
  • Atlas API Access
  • Configuration Methods
• 👩‍💻 Client Integration
  • VSCode
  • Claude
• 🤝 Contributing

Prerequisites

• Node.js (v20 or later)
• MongoDB Atlas account

Installation

VSCode

Prerequisites:

• Node.js v20.x

Step 1: Add the mcp server to VSCode configuration

• Press Cmd + Shift + P and type MCP: Add MCP Server and select it.
• Select command (Stdio).
• Input command npx -y @mongodb-js/mongodb-mcp-server.
• Choose between user / workspace
• Add arguments to the file

Note: the file should look like:

{
    "servers": {
        "MongoDB": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@mongodb-js/mongodb-mcp-server"
            ]
        }
    }
}

Notes: You can configure the server with atlas access, make sure to follow configuration section for more details.

Step 2: Try talking to github copilot

• Can you connect to my mongodb instance?

Claude Desktop

Step 1: Install claude and login

Note: follow instructions at https://claude.ai/download

Step 2: Launch Claude Settings -> Developer -> Edit Config

Paste the mcp server configuration into the file

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "@mongodb-js/mongodb-mcp-server"]
    }
  }
}

Step 3: Close and Relaunch Claude Desktop and click on the hammer icon, the MongoDB MCP server should be detected.

You may experiment asking Can you connect to my mongodb instance?.

🛠️ Supported Tools

Tool List

MongoDB Atlas Tools

• atlas-list-clusters - Lists MongoDB Atlas clusters
• atlas-list-projects - Lists MongoDB Atlas projects
• atlas-inspect-cluster - Inspect a specific MongoDB Atlas cluster
• atlas-create-free-cluster - Create a free MongoDB Atlas cluster
• atlas-create-access-list - Configure IP/CIDR access list for MongoDB Atlas clusters
• atlas-inspect-access-list - Inspect IP/CIDR ranges with access to MongoDB Atlas clusters
• atlas-list-db-users - List MongoDB Atlas database users
• atlas-create-db-user - List MongoDB Atlas database users

MongoDB Database Tools

• connect - Connect to a MongoDB instance
• find - Run a find query against a MongoDB collection
• aggregate - Run an aggregation against a MongoDB collection
• count - Get the number of documents in a MongoDB collection
• insert-one - Insert a single document into a MongoDB collection
• insert-many - Insert multiple documents into a MongoDB collection
• create-index - Create an index for a MongoDB collection
• update-one - Update a single document in a MongoDB collection
• update-many - Update multiple documents in a MongoDB collection
• rename-collection - Rename a MongoDB collection
• delete-one - Delete a single document from a MongoDB collection
• delete-many - Delete multiple documents from a MongoDB collection
• drop-collection - Remove a collection from a MongoDB database
• drop-database - Remove a MongoDB database
• list-databases - List all databases for a MongoDB connection
• list-collections - List all collections for a given database
• collection-indexes - Describe the indexes for a collection
• collection-schema - Describe the schema for a collection
• collection-storage-size - Get the size of a collection in MB
• db-stats - Return statistics about a MongoDB database

Configuration

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

1. Command-line arguments
2. Environment variables

Configuration Options

Option	Description
apiClientId	Atlas API client ID for authentication
apiClientSecret	Atlas API client secret for authentication
connectionString	MongoDB connection string for direct database connections (optional users may choose to inform it on every tool call)
logPath	Folder to store logs

Default Log Path:

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

Atlas API Access

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

1. 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")
   • Select appropriate permissions (for full access, use Organization Owner)
   • Click "Create"

2. 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

3. Add Access List Entry (Optional but recommended):

   • Add your IP address to the API access list

4. Configure the MCP Server:

   • Use one of the configuration methods below to set your apiClientId and apiClientSecret

Configuration Methods

Environment Variables

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

# Set Atlas API credentials
export MDB_MCP_API_CLIENT_ID="your-atlas-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-client-secret"

# Set a custom MongoDB connection string
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:[email protected]/myDatabase"

export MDB_MCP_LOG_PATH="/path/to/logs"

Command-Line Arguments

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

npx -y @mongodb-js/mongodb-mcp-server --apiClientId="your-atlas-client-id" --apiClientSecret="your-atlas-client-secret" --connectionString="mongodb+srv://username:[email protected]/myDatabase" --logPath=/path/to/logs

🤝 Contributing

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