diff --git a/README.md b/README.md index 837b448f..5d95b73a 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,96 @@ # 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. - -> [!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. +A Model Context Protocol server for interacting with MongoDB Databases and MongoDB Atlas. ## 📚 Table of Contents - [🚀 Getting Started](#getting-started) - [Prerequisites](#prerequisites) - - [Installation](#installation) - - [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) - [Atlas API Access](#atlas-api-access) - [Configuration Methods](#configuration-methods) -- [👩‍💻 Client Integration](#client-integration) - - [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 +``` -### VSCode +- 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. -Prerequisites: +## Setup -- Node.js v20.x +### Quick Start -Step 1: Add the mcp server to VSCode configuration +Most MCP clients require a configuration file to be created or modified to add the MCP server. -- 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 +- **Windsurf**:https://docs.windsurf.com/windsurf/mcp +- **VSCode**: https://docs.codeium.com/docs/mcp +- **Claude Desktop**: https://modelcontextprotocol.io/quickstart/user +- **Cursor**: https://docs.cursor.com/context/model-context-protocol -Note: the file should look like: +#### 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": { - "type": "stdio", - "command": "npx", - "args": [ - "-y", - "mongodb-mcp-server" - ] - } + "servers": { + "MongoDB": { + "command": "npx", + "args": [ + "-y", + "mongodb-mcp-server", + "--connectionString", + "mongodb+srv://username:password@cluster.mongodb.net/myDatabase" + ] } + } } ``` -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 +#### Option 2: Atlas API credentials args -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 3: Close and Relaunch Claude Desktop and click on the hammer icon, the MongoDB MCP server should be detected. +#### Other options -You may experiment asking `Can you connect to my mongodb instance?`. +Alternatively you can use environment variables in the config file or set them and run the server via npx. + +- 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 @@ -154,7 +154,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: @@ -250,6 +250,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: @@ -258,6 +293,46 @@ 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" + ] + } + } +} +``` + +##### 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.