TL;DR: The MongoDB MCP server needs `MDB_MCP_CONNECTION_STRING` in the client config's `env` block. Setting it in your terminal does nothing because MCP clients launch servers with a clean environment. Add it to the config, restart the client, done.

```text
Error: MDB_MCP_CONNECTION_STRING environment variable is not set
```

## Fix it

1. Open your MCP client config (`claude_desktop_config.json`, `.mcp.json`, etc.) and add the variable to the server's `env` block:

```json
{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://cluster-host:27017/myDatabase"
      }
    }
  }
}
```

   For Atlas, use the `mongodb+srv://` URL from the Atlas dashboard.

2. Fully quit and restart the client. MCP servers spawn at client launch, not per chat.

   Expected: the server starts, tools like `find` and `aggregate` appear, no startup error.

## When to use this

- The server fails immediately at startup mentioning `MDB_MCP_CONNECTION_STRING`.
- `echo $MDB_MCP_CONNECTION_STRING` works in your terminal but the server still complains.

## When NOT to use this

- The server starts but queries fail with auth or timeout errors. The variable is set; the value is the problem.
- You use Atlas API credentials (`MDB_MCP_API_CLIENT_ID`) instead of a connection string. That is a different auth path.

## Compatibility

- mongodb-mcp-server (all recent versions).
- Claude Desktop, Claude Code, Cursor, Windsurf, VS Code.

## Why it happens

MCP servers are child processes of the client. GUI clients especially do not inherit your interactive shell environment, so `export` in `.bashrc` or a terminal session is invisible to the server. The `env` block in the client config is the only reliable way to pass variables.

## Edge cases

- Special characters in the password (`@`, `/`, `?`, `#`) must be percent-encoded in the URL, or the parser mangles the connection string.
- JSON-escape backslashes and quotes in passwords.
- On Windows, the config path uses the AppData location. Make sure you are editing the file the client actually reads.