@himanshusinghs/mongodb-mcp-server 0.3.0

package/README.md

@@ -0,0 +1,609 @@
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?logo=data:image/svg%2bxml;base64,PHN2ZyBmaWxsPSIjRkZGRkZGIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciICB2aWV3Qm94PSIwIDAgNDggNDgiIHdpZHRoPSIyNHB4IiBoZWlnaHQ9IjI0cHgiPjxwYXRoIGQ9Ik00NC45OTkgMTAuODd2MjYuMjFjMCAxLjAzLS41OSAxLjk3LTEuNTEgMi40Mi0yLjY4IDEuMjktOCAzLjg1LTguMzUgNC4wMS0uMTMuMDctLjM4LjItLjY3LjMxLjM1LS42LjUzLTEuMy41My0yLjAyVjYuMmMwLS43NS0uMi0xLjQ1LS41Ni0yLjA2LjA5LjA0LjE3LjA4LjI0LjExLjIuMSA1Ljk4IDIuODYgOC44IDQuMkM0NC40MDkgOC45IDQ0Ljk5OSA5Ljg0IDQ0Ljk5OSAxMC44N3pNNy40OTkgMjYuMDNjMS42IDEuNDYgMy40MyAzLjEzIDUuMzQgNC44NmwtNC42IDMuNWMtLjc3LjU3LTEuNzguNS0yLjU2LS4wNS0uNS0uMzYtMS44OS0xLjY1LTEuODktMS42NS0xLjAxLS44MS0xLjA2LTIuMzItLjExLTMuMTlDMy42NzkgMjkuNSA1LjE3OSAyOC4xMyA3LjQ5OSAyNi4wM3pNMzEuOTk5IDYuMnYxMC4xMWwtNy42MyA1LjgtNi44NS01LjIxYzQuOTgtNC41MyAxMC4wMS05LjExIDEyLjY1LTExLjUyQzMwLjg2OSA0Ljc0IDMxLjk5OSA1LjI1IDMxLjk5OSA2LjJ6TTMyIDQxLjc5OFYzMS42OUw4LjI0IDEzLjYxYy0uNzctLjU3LTEuNzgtLjUtMi41Ni4wNS0uNS4zNi0xLjg5IDEuNjUtMS44OSAxLjY1LTEuMDEuODEtMS4wNiAyLjMyLS4xMSAzLjE5IDAgMCAyMC4xNDUgMTguMzM4IDI2LjQ4NSAyNC4xMTZDMzAuODcxIDQzLjI2IDMyIDQyLjc1MyAzMiA0MS43OTh6Ii8+PC9zdmc+)](https://insiders.vscode.dev/redirect/mcp/install?name=mongodb&inputs=%5B%7B%22id%22%3A%22connection_string%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22MongoDB%20connection%20string%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mongodb-mcp-server%22%2C%22--readOnly%22%5D%2C%22env%22%3A%7B%22MDB_MCP_CONNECTION_STRING%22%3A%22%24%7Binput%3Aconnection_string%7D%22%7D%7D)
+[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-1e1e1e?logo=data:image/svg%2bxml;base64,PHN2ZyBoZWlnaHQ9IjFlbSIgc3R5bGU9ImZsZXg6bm9uZTtsaW5lLWhlaWdodDoxIiB2aWV3Qm94PSIwIDAgMjQgMjQiIHdpZHRoPSIxZW0iCiAgICB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogICAgPHRpdGxlPkN1cnNvcjwvdGl0bGU+CiAgICA8cGF0aCBkPSJNMTEuOTI1IDI0bDEwLjQyNS02LTEwLjQyNS02TDEuNSAxOGwxMC40MjUgNnoiCiAgICAgICAgZmlsbD0idXJsKCNsb2JlLWljb25zLWN1cnNvcnVuZGVmaW5lZC1maWxsLTApIj48L3BhdGg+CiAgICA8cGF0aCBkPSJNMjIuMzUgMThWNkwxMS45MjUgMHYxMmwxMC40MjUgNnoiIGZpbGw9InVybCgjbG9iZS1pY29ucy1jdXJzb3J1bmRlZmluZWQtZmlsbC0xKSI+PC9wYXRoPgogICAgPHBhdGggZD0iTTExLjkyNSAwTDEuNSA2djEybDEwLjQyNS02VjB6IiBmaWxsPSJ1cmwoI2xvYmUtaWNvbnMtY3Vyc29ydW5kZWZpbmVkLWZpbGwtMikiPjwvcGF0aD4KICAgIDxwYXRoIGQ9Ik0yMi4zNSA2TDExLjkyNSAyNFYxMkwyMi4zNSA2eiIgZmlsbD0iIzU1NSI+PC9wYXRoPgogICAgPHBhdGggZD0iTTIyLjM1IDZsLTEwLjQyNSA2TDEuNSA2aDIwLjg1eiIgZmlsbD0iI2ZmZiI+PC9wYXRoPgogICAgPGRlZnM+CiAgICAgICAgPGxpbmVhckdyYWRpZW50IGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIiBpZD0ibG9iZS1pY29ucy1jdXJzb3J1bmRlZmluZWQtZmlsbC0wIgogICAgICAgICAgICB4MT0iMTEuOTI1IiB4Mj0iMTEuOTI1IiB5MT0iMTIiIHkyPSIyNCI+CiAgICAgICAgICAgIDxzdG9wIG9mZnNldD0iLjE2IiBzdG9wLWNvbG9yPSIjZmZmIiBzdG9wLW9wYWNpdHk9Ii4zOSI+PC9zdG9wPgogICAgICAgICAgICA8c3RvcCBvZmZzZXQ9Ii42NTgiIHN0b3AtY29sb3I9IiNmZmYiIHN0b3Atb3BhY2l0eT0iLjgiPjwvc3RvcD4KICAgICAgICA8L2xpbmVhckdyYWRpZW50PgogICAgICAgIDxsaW5lYXJHcmFkaWVudCBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgaWQ9ImxvYmUtaWNvbnMtY3Vyc29ydW5kZWZpbmVkLWZpbGwtMSIKICAgICAgICAgICAgeDE9IjIyLjM1IiB4Mj0iMTEuOTI1IiB5MT0iNi4wMzciIHkyPSIxMi4xNSI+CiAgICAgICAgICAgIDxzdG9wIG9mZnNldD0iLjE4MiIgc3RvcC1jb2xvcj0iI2ZmZiIgc3RvcC1vcGFjaXR5PSIuMzEiPjwvc3RvcD4KICAgICAgICAgICAgPHN0b3Agb2Zmc2V0PSIuNzE1IiBzdG9wLWNvbG9yPSIjZmZmIiBzdG9wLW9wYWNpdHk9IjAiPjwvc3RvcD4KICAgICAgICA8L2xpbmVhckdyYWRpZW50PgogICAgICAgIDxsaW5lYXJHcmFkaWVudCBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgaWQ9ImxvYmUtaWNvbnMtY3Vyc29ydW5kZWZpbmVkLWZpbGwtMiIKICAgICAgICAgICAgeDE9IjExLjkyNSIgeDI9IjEuNSIgeTE9IjAiIHkyPSIxOCI+CiAgICAgICAgICAgIDxzdG9wIHN0b3AtY29sb3I9IiNmZmYiIHN0b3Atb3BhY2l0eT0iLjYiPjwvc3RvcD4KICAgICAgICAgICAgPHN0b3Agb2Zmc2V0PSIuNjY3IiBzdG9wLWNvbG9yPSIjZmZmIiBzdG9wLW9wYWNpdHk9Ii4yMiI+PC9zdG9wPgogICAgICAgIDwvbGluZWFyR3JhZGllbnQ+CiAgICA8L2RlZnM+Cjwvc3ZnPgo=)](https://cursor.com/install-mcp?name=MongoDB&config=eyJjb21tYW5kIjoibnB4IC15IG1vbmdvZGItbWNwLXNlcnZlciAtLXJlYWRPbmx5In0%3D)
+[![View on Smithery](https://smithery.ai/badge/@mongodb-js/mongodb-mcp-server)](https://smithery.ai/server/@mongodb-js/mongodb-mcp-server)
+
+# MongoDB MCP Server
+
+A Model Context Protocol server for interacting with MongoDB Databases and MongoDB Atlas.
+
+## 📚 Table of Contents
+
+- [🚀 Getting Started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Setup](#setup)
+    - [Quick Start](#quick-start)
+- [🛠️ Supported Tools](#supported-tools)
+  - [MongoDB Atlas Tools](#mongodb-atlas-tools)
+  - [MongoDB Database Tools](#mongodb-database-tools)
+- [📄 Supported Resources](#supported-resources)
+- [⚙️ Configuration](#configuration)
+  - [Configuration Options](#configuration-options)
+  - [Atlas API Access](#atlas-api-access)
+  - [Configuration Methods](#configuration-methods)
+    - [Environment Variables](#environment-variables)
+    - [Command-Line Arguments](#command-line-arguments)
+    - [MCP Client Configuration](#mcp-configuration-file-examples)
+    - [Proxy Support](#proxy-support)
+- [🤝 Contributing](#contributing)
+
+<a name="getting-started"></a>
+
+## Prerequisites
+
+- Node.js
+  - At least 20.19.0
+  - When using v22 then at least v22.12.0
+  - Otherwise any version 23+
+
+```shell
+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](#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
+
+**Note:** When using Atlas API credentials, be sure to assign only the minimum required permissions to your service account. See [Atlas API Permissions](#atlas-api-permissions) for details.
+
+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 args
+
+You can pass your connection string via args, make sure to use a valid username and password.
+
+```json
+{
+  "mcpServers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mongodb-mcp-server",
+        "--connectionString",
+        "mongodb://localhost:27017/myDatabase",
+        "--readOnly"
+      ]
+    }
+  }
+}
+```
+
+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 args
+
+Use your Atlas API Service Accounts credentials. Must follow all the steps in [Atlas API Access](#atlas-api-access) section.
+
+```json
+{
+  "mcpServers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mongodb-mcp-server",
+        "--apiClientId",
+        "your-atlas-service-accounts-client-id",
+        "--apiClientSecret",
+        "your-atlas-service-accounts-client-secret",
+        "--readOnly"
+      ]
+    }
+  }
+}
+```
+
+#### Option 3: Standalone Service using command arguments
+
+Start Server using npx command:
+
+```shell
+ npx -y mongodb-mcp-server@latest --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret" --readOnly
+```
+
+- For a complete list of arguments see [Configuration Options](#configuration-options)
+- To configure your Atlas Service Accounts credentials please refer to [Atlas API Access](#atlas-api-access)
+
+#### Option 4: Standalone Service using environment variables
+
+```shell
+ npx -y mongodb-mcp-server@latest --readOnly
+```
+
+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)
+
+#### Option 5: 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
+
+```shell
+docker run --rm -i \
+  mongodb/mongodb-mcp-server:latest
+```
+
+##### Option B: With MongoDB connection string
+
+```shell
+docker run --rm -i \
+  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
+  -e MDB_MCP_READ_ONLY="true" \
+  mongodb/mongodb-mcp-server:latest
+```
+
+##### Option C: With Atlas API credentials
+
+```shell
+docker run --rm -i \
+  -e MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id" \
+  -e MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret" \
+  -e MDB_MCP_READ_ONLY="true" \
+  mongodb/mongodb-mcp-server:latest
+```
+
+##### Docker in MCP Configuration File
+
+Without options:
+
+```json
+{
+  "mcpServers": {
+    "MongoDB": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-e",
+        "MDB_MCP_READ_ONLY=true",
+        "-i",
+        "mongodb/mongodb-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
+With connection string:
+
+```json
+{
+  "mcpServers": {
+    "MongoDB": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
+        "-e",
+        "MDB_MCP_READ_ONLY=true",
+        "mongodb/mongodb-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
+With Atlas API credentials:
+
+```json
+{
+  "mcpServers": {
+    "MongoDB": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "MDB_MCP_READ_ONLY=true",
+        "-e",
+        "MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id",
+        "-e",
+        "MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret",
+        "mongodb/mongodb-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
+#### Option 6: 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](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).
+
+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:
+
+```shell
+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:
+
+```shell
+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-list-orgs` - Lists MongoDB Atlas organizations
+- `atlas-list-projects` - Lists MongoDB Atlas projects
+- `atlas-create-project` - Creates a new MongoDB Atlas project
+- `atlas-list-clusters` - Lists MongoDB Atlas clusters
+- `atlas-inspect-cluster` - Inspect a specific MongoDB Atlas cluster
+- `atlas-create-free-cluster` - Create a free MongoDB Atlas cluster
+- `atlas-connect-cluster` - Connects to MongoDB Atlas cluster
+- `atlas-inspect-access-list` - Inspect IP/CIDR ranges with access to MongoDB Atlas clusters
+- `atlas-create-access-list` - Configure IP/CIDR access list for MongoDB Atlas clusters
+- `atlas-list-db-users` - List MongoDB Atlas database users
+- `atlas-create-db-user` - Creates a MongoDB Atlas database user
+- `atlas-list-alerts` - List MongoDB Atlas Alerts for a Project
+
+NOTE: atlas tools are only available when you set credentials on [configuration](#configuration) section.
+
+#### 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
+- `export` - Export query or aggregation results to EJSON format. Creates a uniquely named export accessible via the `exported-data` resource.
+
+## 📄 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
+
+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
+
+| CLI Option                | Environment Variable                 | Default    | Description                                                                                                                                                   |
+| ------------------------- | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiClientId`             | `MDB_MCP_API_CLIENT_ID`              | <not set>  | Atlas API client ID for authentication. Required for running Atlas tools.                                                                                     |
+| `apiClientSecret`         | `MDB_MCP_API_CLIENT_SECRET`          | <not set>  | Atlas API client secret for authentication. Required for running Atlas tools.                                                                                 |
+| `connectionString`        | `MDB_MCP_CONNECTION_STRING`          | <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. |
+| `loggers`                 | `MDB_MCP_LOGGERS`                    | disk,mcp   | Comma separated values, possible values are `mcp`, `disk` and `stderr`. See [Logger Options](#logger-options) for details.                                    |
+| `logPath`                 | `MDB_MCP_LOG_PATH`                   | see note\* | Folder to store logs.                                                                                                                                         |
+| `disabledTools`           | `MDB_MCP_DISABLED_TOOLS`             | <not set>  | An array of tool names, operation types, and/or categories of tools that will be disabled.                                                                    |
+| `readOnly`                | `MDB_MCP_READ_ONLY`                  | false      | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations.                                         |
+| `indexCheck`              | `MDB_MCP_INDEX_CHECK`                | false      | When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan.                                         |
+| `telemetry`               | `MDB_MCP_TELEMETRY`                  | enabled    | When set to disabled, disables telemetry collection.                                                                                                          |
+| `transport`               | `MDB_MCP_TRANSPORT`                  | stdio      | Either 'stdio' or 'http'.                                                                                                                                     |
+| `httpPort`                | `MDB_MCP_HTTP_PORT`                  | 3000       | Port number.                                                                                                                                                  |
+| `httpHost`                | `MDB_MCP_HTTP_HOST`                  | 127.0.0.1  | Host to bind the http server.                                                                                                                                 |
+| `idleTimeoutMs`           | `MDB_MCP_IDLE_TIMEOUT_MS`            | 600000     | Idle timeout for a client to disconnect (only applies to http transport).                                                                                     |
+| `notificationTimeoutMs`   | `MDB_MCP_NOTIFICATION_TIMEOUT_MS`    | 540000     | Notification timeout for a client to be aware of diconnect (only applies to http transport).                                                                  |
+| `exportsPath`             | `MDB_MCP_EXPORTS_PATH`               | see note\* | Folder to store exported data files.                                                                                                                          |
+| `exportTimeoutMs`         | `MDB_MCP_EXPORT_TIMEOUT_MS`          | 300000     | Time in milliseconds after which an export is considered expired and eligible for cleanup.                                                                    |
+| `exportCleanupIntervalMs` | `MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS` | 120000     | Time in milliseconds between export cleanup cycles that remove expired export files.                                                                          |
+
+#### 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
+
+```shell
+export MDB_MCP_LOGGERS="disk,stderr"
+```
+
+##### Example: Set logger via command-line argument
+
+```shell
+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.
+
+#### 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, list collections, 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.
+
+#### 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`
+
+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`
+
+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).
+
+#### 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`
+
+### 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](#atlas-api-permissions) section below.
+
+1. **Create a Service Account:**
+   - Log in to MongoDB Atlas at [cloud.mongodb.com](https://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](#atlas-api-permissions) for details.
+   - Click "Create"
+
+To learn more about Service Accounts, check the [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/).
+
+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:**
+   - 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`
+
+### 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](https://www.mongodb.com/docs/atlas/reference/user-roles/#service-user-roles).
+
+### Configuration Methods
+
+#### Environment Variables
+
+Set environment variables with the prefix `MDB_MCP_` followed by the option name in uppercase with underscores:
+
+```shell
+# 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"
+
+export MDB_MCP_LOG_PATH="/path/to/logs"
+
+```
+
+#### MCP configuration file examples
+
+##### Connection String with environment variables
+
+```json
+{
+  "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
+
+```json
+{
+  "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:
+
+```shell
+npx -y mongodb-mcp-server@latest --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret" --connectionString="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" --logPath=/path/to/logs --readOnly --indexCheck
+```
+
+#### MCP configuration file examples
+
+##### Connection String with command-line arguments
+
+```json
+{
+  "mcpServers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mongodb-mcp-server",
+        "--connectionString",
+        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
+        "--readOnly"
+      ]
+    }
+  }
+}
+```
+
+##### Atlas API credentials with command-line arguments
+
+```json
+{
+  "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.
+
+## 🤝Contributing
+
+Interested in contributing? Great! Please check our [Contributing Guide](CONTRIBUTING.md) for guidelines on code contributions, standards, adding new tools, and troubleshooting information.

package/dist/cjs/common/atlas/accessListUtils.d.ts

@@ -0,0 +1,15 @@
+import type { ApiClient } from "./apiClient.js";
+export declare const DEFAULT_ACCESS_LIST_COMMENT = "Added by MongoDB MCP Server to enable tool access";
+export declare function makeCurrentIpAccessListEntry(apiClient: ApiClient, projectId: string, comment?: string): Promise<{
+    groupId: string;
+    ipAddress: string;
+    comment: string;
+}>;
+/**
+ * Ensures the current public IP is in the access list for the given Atlas project.
+ * If the IP is already present, this is a no-op.
+ * @param apiClient The Atlas API client instance
+ * @param projectId The Atlas project ID
+ */
+export declare function ensureCurrentIpInAccessList(apiClient: ApiClient, projectId: string): Promise<void>;
+//# sourceMappingURL=accessListUtils.d.ts.map

package/dist/cjs/common/atlas/accessListUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessListUtils.d.ts","sourceRoot":"","sources":["../../../../src/common/atlas/accessListUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,eAAO,MAAM,2BAA2B,sDAAsD,CAAC;AAE/F,wBAAsB,4BAA4B,CAC9C,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,MAAoC,GAC9C,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAOlE;AAED;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BxG"}