From c5d5c13fab43f2db60243b5e24845a758ab0d6aa Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Tue, 29 Apr 2025 17:40:13 +0100 Subject: [PATCH 1/9] chore: update config docs --- README.md | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 837b448f..8751c9d6 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ A Model Context Protocol server for interacting with MongoDB Atlas. This project - [🚀 Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Installation](#installation) + - [WindSurf](#windsurf) - [VSCode](#vscode) - [Claude Desktop](#claude) - [🛠️ Supported Tools](#supported-tools) @@ -19,6 +20,7 @@ A Model Context Protocol server for interacting with MongoDB Atlas. This project - [Atlas API Access](#atlas-api-access) - [Configuration Methods](#configuration-methods) - [👩‍💻 Client Integration](#client-integration) + - [WindSurf](#windsurf) - [VSCode](#vscode) - [Claude](#claude) - [🤝 Contributing](#contributing) @@ -30,6 +32,38 @@ A Model Context Protocol server for interacting with MongoDB Atlas. This project ## Installation + + +### WindSurf + +Prerequisites: + +- Node.js v20.x +- WindSurf installed on your machine + +The latest instructions can be found at https://docs.windsurf.com/windsurf/mcp + +Step 1: Create MCP configuration file + + +Create or edit the configuration file at `~/.codeium/windsurf/mcp_config.json`: + +```json +{ + "servers": { + "MongoDB": { + "command": "npx", + "args": [ + "-y", + "mongodb-mcp-server" + ] + } + } +} +``` + +Step 2: Follow the [configuration](#configuration) section for more details on how to connect to a MongoDB instance or Atlas. + ### VSCode Prerequisites: @@ -61,11 +95,8 @@ Note: the file should look like: } ``` -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 +Step 2: Follow the [configuration](#configuration) section for more details on how to connect to a MongoDB instance or Atlas. -- Can you connect to my mongodb instance? ### Claude Desktop @@ -90,7 +121,7 @@ Paste the mcp server configuration into the file 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?`. +Follow the [configuration](#configuration) section for more details on how to connect to a MongoDB instance or Atlas. ## 🛠️ Supported Tools From b4f0395517f0342c255902339056c245686f7d99 Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Tue, 29 Apr 2025 17:41:37 +0100 Subject: [PATCH 2/9] update prerequisites --- README.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8751c9d6..d23486fc 100644 --- a/README.md +++ b/README.md @@ -32,15 +32,13 @@ A Model Context Protocol server for interacting with MongoDB Atlas. This project ## Installation +Common prerequisites: +- Node.js v20.x +- A MongoDB connection string or Atlas API credentials ### WindSurf -Prerequisites: - -- Node.js v20.x -- WindSurf installed on your machine - The latest instructions can be found at https://docs.windsurf.com/windsurf/mcp Step 1: Create MCP configuration file @@ -66,10 +64,6 @@ Step 2: Follow the [configuration](#configuration) section for more details on h ### 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. From 735d1ddc6f929de655839d4a6504de2d519a5d3c Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Tue, 29 Apr 2025 17:51:49 +0100 Subject: [PATCH 3/9] update --- README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 96 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index d23486fc..58373cc3 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ A Model Context Protocol server for interacting with MongoDB Atlas. This project Common prerequisites: - Node.js v20.x -- A MongoDB connection string or Atlas API credentials +- A MongoDB connection string or Atlas API credentials, the Server will not start unless configured, see [configuration](#configuration) section for more details. ### WindSurf @@ -43,7 +43,6 @@ The latest instructions can be found at https://docs.windsurf.com/windsurf/mcp Step 1: Create MCP configuration file - Create or edit the configuration file at `~/.codeium/windsurf/mcp_config.json`: ```json @@ -51,16 +50,18 @@ Create or edit the configuration file at `~/.codeium/windsurf/mcp_config.json`: "servers": { "MongoDB": { "command": "npx", - "args": [ - "-y", - "mongodb-mcp-server" - ] + "args": ["-y", "mongodb-mcp-server"] } } } ``` -Step 2: Follow the [configuration](#configuration) section for more details on how to connect to a MongoDB instance or Atlas. +Step 2: Setup a connection string or Atlas API credentials + +- Option 1: Connection String via args [example](#connection-string-with-args) +- Option 2: Atlas API credentials via args [example](#atlas-api-credentials-with-args) +- Option 3: Connection String via environment variables [example](#connection-string-with-environment-variables) +- Option 4: Atlas API credentials via environment variables [example](#atlas-api-credentials-with-environment-variables) ### VSCode @@ -89,16 +90,16 @@ Note: the file should look like: } ``` -Step 2: Follow the [configuration](#configuration) section for more details on how to connect to a MongoDB instance or Atlas. +Step 2: Setup a connection string or Atlas API credentials +- Option 1: Connection String via args [example](#connection-string-with-args) +- Option 2: Atlas API credentials via args [example](#atlas-api-credentials-with-args) +- Option 3: Connection String via environment variables [example](#connection-string-with-environment-variables) +- Option 4: Atlas API credentials via environment variables [example](#atlas-api-credentials-with-environment-variables) ### Claude Desktop -Step 1: Install claude and login - -Note: follow instructions at https://claude.ai/download - -Step 2: Launch Claude Settings -> Developer -> Edit Config +Step 1: Launch Claude Settings -> Developer -> Edit Config Paste the mcp server configuration into the file @@ -113,9 +114,12 @@ Paste the mcp server configuration into the file } ``` -Step 3: Close and Relaunch Claude Desktop and click on the hammer icon, the MongoDB MCP server should be detected. +Step 2: Setup a connection string or Atlas API credentials -Follow the [configuration](#configuration) section for more details on how to connect to a MongoDB instance or Atlas. +- Option 1: Connection String via args [example](#connection-string-with-args) +- Option 2: Atlas API credentials via args [example](#atlas-api-credentials-with-args) +- Option 3: Connection String via environment variables [example](#connection-string-with-environment-variables) +- Option 4: Atlas API credentials via environment variables [example](#atlas-api-credentials-with-environment-variables) ## 🛠️ Supported Tools @@ -275,6 +279,41 @@ export MDB_MCP_LOG_PATH="/path/to/logs" ``` +#### MCP configuration file examples + +##### Connection String with environment variables + +```json +{ + "servers": { + "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 + +```json +{ + "servers": { + "MongoDB": { + "command": "npx", + "args": ["-y", "mongodb-mcp-server"], + "env": { + "MDB_MCP_API_CLIENT_ID": "your-atlas-client-id", + "MDB_MCP_API_CLIENT_SECRET": "your-atlas-client-secret" + } + } + } +} +``` + #### Command-Line Arguments Pass configuration options as command-line arguments when starting the server: @@ -283,6 +322,48 @@ Pass configuration options as command-line arguments when starting the server: npx -y mongodb-mcp-server --apiClientId="your-atlas-client-id" --apiClientSecret="your-atlas-client-secret" --connectionString="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" --logPath=/path/to/logs ``` +#### MCP configuration file examples + +##### Connection String with command-line arguments + +```json +{ + "servers": { + "MongoDB": { + "command": "npx", + "args": [ + "-y", + "mongodb-mcp-server", + "--connectionString", + "mongodb+srv://username:password@cluster.mongodb.net/myDatabase", + "--logPath", + "/path/to/logs" + ] + } + } +} +``` + +##### Atlas API credentials with command-line arguments + +```json +{ + "servers": { + "MongoDB": { + "command": "npx", + "args": [ + "-y", + "mongodb-mcp-server", + "--apiClientId", + "your-atlas-client-id", + "--apiClientSecret", + "your-atlas-client-secret" + ] + } + } +} +``` + ## 🤝 Contributing Interested in contributing? Great! Please check our [Contributing Guide](CONTRIBUTING.md) for guidelines on code contributions, standards, adding new tools, and troubleshooting information. From 525e589164a9fdf752d66719ef5ae1c5c646c178 Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Wed, 30 Apr 2025 11:13:56 +0100 Subject: [PATCH 4/9] remove banner --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 58373cc3..c9f70df3 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,6 @@ 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 From 240e199049a46c045b4e3cf584b288ce2ab047ba Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Wed, 30 Apr 2025 11:46:22 +0100 Subject: [PATCH 5/9] update --- README.md | 126 ++++++++++++++++++++++-------------------------------- 1 file changed, 52 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index c9f70df3..20c97b75 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,101 @@ # MongoDB 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. - +A Model Context Protocol server for interacting with MongoDB Databases and MongoDB Atlas. ## 📚 Table of Contents - [🚀 Getting Started](#getting-started) - [Prerequisites](#prerequisites) - - [Installation](#installation) - - [WindSurf](#windsurf) - - [VSCode](#vscode) - - [Claude Desktop](#claude) + - [Setup](#setup) + - [Quick Start](#quick-start) - [🛠️ Supported Tools](#supported-tools) - - [Tool List](#tool-list) + - [MongoDB Atlas Tools](#mongodb-atlas-tools) + - [MongoDB Database Tools](#mongodb-database-tools) - [⚙️ Configuration](#configuration) - [Configuration Options](#configuration-options) + - [Connection Options](#configuration-options) + - [Log Path](#log-path) + - [Disabled Tools](#disabled-tools) + - [Read-Only Mode](#read-only-mode) + - [Telemetry Settings](#telemetry) - [Atlas API Access](#atlas-api-access) - [Configuration Methods](#configuration-methods) -- [👩‍💻 Client Integration](#client-integration) - - [WindSurf](#windsurf) - - [VSCode](#vscode) - - [Claude](#claude) + - [Environment Variables](#environment-variables) + - [Command-Line Arguments](#command-line-arguments) + - [MCP Client Configuration](#mcp-configuration-file-examples) - [🤝 Contributing](#contributing) ## Prerequisites - Node.js (v20 or later) -- MongoDB Atlas account -## Installation +```shell +node -v +``` -Common prerequisites: +- A MongoDB connection string or Atlas API credentials, **_the Server will not start unless configured_**. + - **_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](#atlas-api-access) for more details. + - If you have a MongoDB connection string, you can use it directly to connect to your MongoDB instance. -- Node.js v20.x -- A MongoDB connection string or Atlas API credentials, the Server will not start unless configured, see [configuration](#configuration) section for more details. +## Setup -### WindSurf +### Quick Start -The latest instructions can be found at https://docs.windsurf.com/windsurf/mcp +Most MCP clients require a configuration file to be created or modified to add the MCP server. -Step 1: Create MCP configuration file +- **Windsurf** ([latest instructions](https://docs.windsurf.com/windsurf/mcp)): Save the file in `~/.codeium/windsurf/mcp_config.json` +- **VSCode**: https://docs.codeium.com/docs/mcp +- **Claude Desktop**: https://modelcontextprotocol.io/quickstart/user +- **Cursor**: follow https://docs.cursor.com/context/model-context-protocol -Create or edit the configuration file at `~/.codeium/windsurf/mcp_config.json`: +#### Option 1: Connection String args + +You can pass your connection string via args, make sure to use a valid username and password. ```json { "servers": { "MongoDB": { "command": "npx", - "args": ["-y", "mongodb-mcp-server"] + "args": [ + "-y", + "mongodb-mcp-server", + "--connectionString", + "mongodb+srv://username:password@cluster.mongodb.net/myDatabase" + ] } } } ``` -Step 2: Setup a connection string or Atlas API credentials - -- Option 1: Connection String via args [example](#connection-string-with-args) -- Option 2: Atlas API credentials via args [example](#atlas-api-credentials-with-args) -- Option 3: Connection String via environment variables [example](#connection-string-with-environment-variables) -- Option 4: Atlas API credentials via environment variables [example](#atlas-api-credentials-with-environment-variables) - -### VSCode - -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-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-mcp-server" - ] - } - } -} -``` - -Step 2: Setup a connection string or Atlas API credentials - -- Option 1: Connection String via args [example](#connection-string-with-args) -- Option 2: Atlas API credentials via args [example](#atlas-api-credentials-with-args) -- Option 3: Connection String via environment variables [example](#connection-string-with-environment-variables) -- Option 4: Atlas API credentials via environment variables [example](#atlas-api-credentials-with-environment-variables) +#### Option 2: Atlas API credentials args -### Claude Desktop - -Step 1: Launch Claude Settings -> Developer -> Edit Config - -Paste the mcp server configuration into the file +Use your Atlas API Service Account credentials. More details in the [Atlas API Access](#atlas-api-access) section. ```json { - "mcpServers": { + "servers": { "MongoDB": { "command": "npx", - "args": ["-y", "mongodb-mcp-server"] + "args": [ + "-y", + "mongodb-mcp-server", + "--apiClientId", + "your-atlas-client-id", + "--apiClientSecret", + "your-atlas-client-secret" + ] } } } ``` -Step 2: Setup a connection string or Atlas API credentials +#### Other options + +Alternatively you can use environment variables in the config file or set them and run the server via npx. -- Option 1: Connection String via args [example](#connection-string-with-args) -- Option 2: Atlas API credentials via args [example](#atlas-api-credentials-with-args) -- Option 3: Connection String via environment variables [example](#connection-string-with-environment-variables) -- Option 4: Atlas API credentials via environment variables [example](#atlas-api-credentials-with-environment-variables) +- Connection String via environment variables [example](#connection-string-with-environment-variables) +- Atlas API credentials via environment variables [example](#atlas-api-credentials-with-environment-variables) ## 🛠️ Supported Tools @@ -181,7 +159,7 @@ The MongoDB MCP Server can be configured using multiple methods, with the follow | `readOnly` | When set to true, only allows read and metadata operation types, disabling create/update/delete operations | | `telemetry` | When set to disabled, disables telemetry collection | -#### `logPath` +#### Log Path Default log location is as follows: From 6282952b94d7a3fe5bb08ee0eadd3fe2f2969c78 Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Wed, 30 Apr 2025 11:47:46 +0100 Subject: [PATCH 6/9] remove log arg --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 20c97b75..c42d3b8a 100644 --- a/README.md +++ b/README.md @@ -312,8 +312,6 @@ npx -y mongodb-mcp-server --apiClientId="your-atlas-client-id" --apiClientSecret "mongodb-mcp-server", "--connectionString", "mongodb+srv://username:password@cluster.mongodb.net/myDatabase", - "--logPath", - "/path/to/logs" ] } } From aa4bf7bdc9ae7d5311d6e539af140566d9651a09 Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Wed, 30 Apr 2025 11:50:03 +0100 Subject: [PATCH 7/9] reduce table of contents --- README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/README.md b/README.md index c42d3b8a..e47070b1 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,6 @@ A Model Context Protocol server for interacting with MongoDB Databases and Mongo - [MongoDB Database Tools](#mongodb-database-tools) - [⚙️ Configuration](#configuration) - [Configuration Options](#configuration-options) - - [Connection Options](#configuration-options) - - [Log Path](#log-path) - - [Disabled Tools](#disabled-tools) - - [Read-Only Mode](#read-only-mode) - - [Telemetry Settings](#telemetry) - [Atlas API Access](#atlas-api-access) - [Configuration Methods](#configuration-methods) - [Environment Variables](#environment-variables) From 484390db5b168f6995f1bfaa8cb3f89d75222c44 Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Wed, 30 Apr 2025 11:58:13 +0100 Subject: [PATCH 8/9] lint --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e47070b1..36d97f78 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ node -v Most MCP clients require a configuration file to be created or modified to add the MCP server. -- **Windsurf** ([latest instructions](https://docs.windsurf.com/windsurf/mcp)): Save the file in `~/.codeium/windsurf/mcp_config.json` +- **Windsurf**: On MacOS, save the file in `~/.codeium/windsurf/mcp_config.json` or check the[latest instructions](https://docs.windsurf.com/windsurf/mcp) for your environment - **VSCode**: https://docs.codeium.com/docs/mcp - **Claude Desktop**: https://modelcontextprotocol.io/quickstart/user - **Cursor**: follow https://docs.cursor.com/context/model-context-protocol @@ -89,8 +89,8 @@ Use your Atlas API Service Account credentials. More details in the [Atlas API A Alternatively you can use environment variables in the config file or set them and run the server via npx. -- Connection String via environment variables [example](#connection-string-with-environment-variables) -- Atlas API credentials via environment variables [example](#atlas-api-credentials-with-environment-variables) +- Connection String via environment variables in the MCP file [example](#connection-string-with-environment-variables) +- Atlas API credentials via environment variables in the MCP file [example](#atlas-api-credentials-with-environment-variables) ## 🛠️ Supported Tools @@ -306,7 +306,7 @@ npx -y mongodb-mcp-server --apiClientId="your-atlas-client-id" --apiClientSecret "-y", "mongodb-mcp-server", "--connectionString", - "mongodb+srv://username:password@cluster.mongodb.net/myDatabase", + "mongodb+srv://username:password@cluster.mongodb.net/myDatabase" ] } } From 78705ad8b8be3759d64d6cbb3acd6e178a03710a Mon Sep 17 00:00:00 2001 From: Bianca Lisle Date: Wed, 30 Apr 2025 12:40:15 +0100 Subject: [PATCH 9/9] Address comment: update windusrf description --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 36d97f78..5d95b73a 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,10 @@ node -v Most MCP clients require a configuration file to be created or modified to add the MCP server. -- **Windsurf**: On MacOS, save the file in `~/.codeium/windsurf/mcp_config.json` or check the[latest instructions](https://docs.windsurf.com/windsurf/mcp) for your environment +- **Windsurf**:https://docs.windsurf.com/windsurf/mcp - **VSCode**: https://docs.codeium.com/docs/mcp - **Claude Desktop**: https://modelcontextprotocol.io/quickstart/user -- **Cursor**: follow https://docs.cursor.com/context/model-context-protocol +- **Cursor**: https://docs.cursor.com/context/model-context-protocol #### Option 1: Connection String args