Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit ed8c19f

Browse files
chore: update readme following sec recommendations MCP-198 (#547)
1 parent 17b544b commit ed8c19f

File tree

1 file changed

+108
-44
lines changed

1 file changed

+108
-44
lines changed

‎README.md‎

Lines changed: 108 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,9 @@ node -v
4747

4848
### Quick Start
4949

50-
**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.
50+
> **🔒 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](#atlas-api-permissions) for details.
51+
52+
> **🔒 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.
5153
5254
Most MCP clients require a configuration file to be created or modified to add the MCP server.
5355

@@ -60,30 +62,27 @@ Note: The configuration file syntax can be different across clients. Please refe
6062

6163
> **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.
6264
63-
#### Option 1: Connection String args
65+
#### Option 1: Connection String
6466

65-
You can pass your connection string via args, make sure to use a valid username and password.
67+
You can pass your connection string via environment variables, make sure to use a valid username and password.
6668

6769
```json
6870
{
6971
"mcpServers": {
7072
"MongoDB": {
7173
"command": "npx",
72-
"args": [
73-
"-y",
74-
"mongodb-mcp-server",
75-
"--connectionString",
76-
"mongodb://localhost:27017/myDatabase",
77-
"--readOnly"
78-
]
74+
"args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
75+
"env": {
76+
"MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
77+
}
7978
}
8079
}
8180
}
8281
```
8382

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

86-
#### Option 2: Atlas API credentials args
85+
#### Option 2: Atlas API Credentials
8786

8887
Use your Atlas API Service Accounts credentials. Must follow all the steps in [Atlas API Access](#atlas-api-access) section.
8988

@@ -92,43 +91,37 @@ Use your Atlas API Service Accounts credentials. Must follow all the steps in [A
9291
"mcpServers": {
9392
"MongoDB": {
9493
"command": "npx",
95-
"args": [
96-
"-y",
97-
"mongodb-mcp-server",
98-
"--apiClientId",
99-
"your-atlas-service-accounts-client-id",
100-
"--apiClientSecret",
101-
"your-atlas-service-accounts-client-secret",
102-
"--readOnly"
103-
]
94+
"args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
95+
"env": {
96+
"MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
97+
"MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
98+
}
10499
}
105100
}
106101
}
107102
```
108103

109-
#### Option 3: Standalone Service using command arguments
104+
#### Option 3: Standalone Service using environment variables and command line arguments
110105

111-
Start Server using npx command:
106+
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.
112107

113108
```shell
114-
npx -y mongodb-mcp-server@latest --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret" --readOnly
115-
```
116-
117-
- For a complete list of arguments see [Configuration Options](#configuration-options)
118-
- To configure your Atlas Service Accounts credentials please refer to [Atlas API Access](#atlas-api-access)
119-
120-
#### Option 4: Standalone Service using environment variables
109+
# Set your credentials as environment variables first
110+
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
111+
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
121112

122-
```shell
123-
npx -y mongodb-mcp-server@latest --readOnly
113+
# Then start the server
114+
npx -y mongodb-mcp-server@latest --readOnly
124115
```
125116

126-
You can use environment variables in the config file or set them and run the server via npx.
117+
> **💡 Platform Note:** The examples above use Unix/Linux/macOS syntax. For Windows users, see [Environment Variables](#environment-variables) for platform-specific instructions.
127118
119+
- For a complete list of configuration options see [Configuration Options](#configuration-options)
120+
- To configure your Atlas Service Accounts credentials please refer to [Atlas API Access](#atlas-api-access)
128121
- Connection String via environment variables in the MCP file [example](#connection-string-with-environment-variables)
129122
- Atlas API credentials via environment variables in the MCP file [example](#atlas-api-credentials-with-environment-variables)
130123

131-
#### Option 5: Using Docker
124+
#### Option 4: Using Docker
132125

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

@@ -146,22 +139,35 @@ docker run --rm -i \
146139
##### Option B: With MongoDB connection string
147140

148141
```shell
142+
# Set your credentials as environment variables first
143+
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
144+
145+
# Then start the docker container
149146
docker run --rm -i \
150-
-e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
147+
-e MDB_MCP_CONNECTION_STRING \
151148
-e MDB_MCP_READ_ONLY="true" \
152149
mongodb/mongodb-mcp-server:latest
153150
```
154151

152+
> **💡 Platform Note:** The examples above use Unix/Linux/macOS syntax. For Windows users, see [Environment Variables](#environment-variables) for platform-specific instructions.
153+
155154
##### Option C: With Atlas API credentials
156155

157156
```shell
157+
# Set your credentials as environment variables first
158+
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
159+
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
160+
161+
# Then start the docker container
158162
docker run --rm -i \
159-
-e MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id" \
160-
-e MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret" \
163+
-e MDB_MCP_API_CLIENT_ID \
164+
-e MDB_MCP_API_CLIENT_SECRET \
161165
-e MDB_MCP_READ_ONLY="true" \
162166
mongodb/mongodb-mcp-server:latest
163167
```
164168

169+
> **💡 Platform Note:** The examples above use Unix/Linux/macOS syntax. For Windows users, see [Environment Variables](#environment-variables) for platform-specific instructions.
170+
165171
##### Docker in MCP Configuration File
166172

167173
Without options:
@@ -196,11 +202,14 @@ With connection string:
196202
"--rm",
197203
"-i",
198204
"-e",
199-
"MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
205+
"MDB_MCP_CONNECTION_STRING",
200206
"-e",
201207
"MDB_MCP_READ_ONLY=true",
202208
"mongodb/mongodb-mcp-server:latest"
203-
]
209+
],
210+
"env": {
211+
"MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
212+
}
204213
}
205214
}
206215
}
@@ -220,17 +229,21 @@ With Atlas API credentials:
220229
"-e",
221230
"MDB_MCP_READ_ONLY=true",
222231
"-e",
223-
"MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id",
232+
"MDB_MCP_API_CLIENT_ID",
224233
"-e",
225-
"MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret",
234+
"MDB_MCP_API_CLIENT_SECRET",
226235
"mongodb/mongodb-mcp-server:latest"
227-
]
236+
],
237+
"env": {
238+
"MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
239+
"MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
240+
}
228241
}
229242
}
230243
}
231244
```
232245

233-
#### Option 6: Running as an HTTP Server
246+
#### Option 5: Running as an HTTP Server
234247

235248
> **⚠️ 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.**
236249
@@ -316,6 +329,8 @@ NOTE: atlas tools are only available when you set credentials on [configuration]
316329

317330
## Configuration
318331

332+
> **🔒 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.
333+
319334
The MongoDB MCP Server can be configured using multiple methods, with the following precedence (highest to lowest):
320335

321336
1. Command-line arguments
@@ -361,6 +376,8 @@ You can combine multiple loggers, e.g. `--loggers disk stderr` or `export MDB_MC
361376
export MDB_MCP_LOGGERS="disk,stderr"
362377
```
363378

379+
> **💡 Platform Note:** For Windows users, see [Environment Variables](#environment-variables) for platform-specific instructions.
380+
364381
##### Example: Set logger via command-line argument
365382

366383
```shell
@@ -411,6 +428,8 @@ You can enable read-only mode using:
411428
- **Environment variable**: `export MDB_MCP_READ_ONLY=true`
412429
- **Command-line argument**: `--readOnly`
413430

431+
> **💡 Platform Note:** For Windows users, see [Environment Variables](#environment-variables) for platform-specific instructions.
432+
414433
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.
415434

416435
#### Index Check Mode
@@ -424,6 +443,8 @@ You can enable index check mode using:
424443
- **Environment variable**: `export MDB_MCP_INDEX_CHECK=true`
425444
- **Command-line argument**: `--indexCheck`
426445

446+
> **💡 Platform Note:** For Windows users, see [Environment Variables](#environment-variables) for platform-specific instructions.
447+
427448
When index check mode is active, you'll see an error message if a query is rejected due to not using an index.
428449

429450
#### Exports
@@ -447,6 +468,8 @@ You can disable telemetry using:
447468
- **Command-line argument**: `--telemetry disabled`
448469
- **DO_NOT_TRACK environment variable**: `export DO_NOT_TRACK=1`
449470

471+
> **💡 Platform Note:** For Windows users, see [Environment Variables](#environment-variables) for platform-specific instructions.
472+
450473
### Atlas API Access
451474

452475
To use the Atlas API tools, you'll need to create a service account in MongoDB Atlas:
@@ -500,16 +523,43 @@ For a full list of roles and their privileges, see the [Atlas User Roles documen
500523

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

503-
```shell
526+
**Linux/macOS (bash/zsh):**
527+
528+
```bash
504529
# Set Atlas API credentials (via Service Accounts)
505530
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
506531
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
507532

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

536+
# Set log path
511537
export MDB_MCP_LOG_PATH="/path/to/logs"
538+
```
512539

540+
**Windows Command Prompt (cmd):**
541+
542+
```cmd
543+
set "MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id"
544+
set "MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret"
545+
546+
set "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
547+
548+
set "MDB_MCP_LOG_PATH=C:\path\to\logs"
549+
```
550+
551+
**Windows PowerShell:**
552+
553+
```powershell
554+
# Set Atlas API credentials (via Service Accounts)
555+
$env:MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
556+
$env:MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
557+
558+
# Set a custom MongoDB connection string
559+
$env:MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
560+
561+
# Set log path
562+
$env:MDB_MCP_LOG_PATH="C:\path\to\logs"
513563
```
514564

515565
#### MCP configuration file examples
@@ -551,14 +601,26 @@ export MDB_MCP_LOG_PATH="/path/to/logs"
551601

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

604+
> **🔒 Security Note:** For sensitive configuration like API credentials and connection strings, use environment variables instead of command-line arguments.
605+
554606
```shell
555-
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
607+
# Set sensitive data as environment variable
608+
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
609+
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
610+
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
611+
612+
# Start the server with command line arguments
613+
npx -y mongodb-mcp-server@latest --logPath=/path/to/logs --readOnly --indexCheck
556614
```
557615

616+
> **💡 Platform Note:** The examples above use Unix/Linux/macOS syntax. For Windows users, see [Environment Variables](#environment-variables) for platform-specific instructions.
617+
558618
#### MCP configuration file examples
559619

560620
##### Connection String with command-line arguments
561621

622+
> **🔒 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](#connection-string-with-environment-variables)
623+
562624
```json
563625
{
564626
"mcpServers": {
@@ -578,6 +640,8 @@ npx -y mongodb-mcp-server@latest --apiClientId="your-atlas-service-accounts-clie
578640

579641
##### Atlas API credentials with command-line arguments
580642

643+
> **🔒 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](#atlas-api-credentials-with-environment-variables)
644+
581645
```json
582646
{
583647
"mcpServers": {

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /