MongoDB MCP Server

Common errors

• Failed to start MongoDB MCP Server: MongoServerError: Authentication failed.

  cause Incorrect MongoDB connection string, invalid username/password, or missing Atlas API credentials.
  fix Verify the `MONGODB_URI` environment variable or connection string provided in the server configuration. Ensure Atlas API credentials (client ID and private key) are correctly set up and have the necessary permissions. Test the connection string independently using `mongosh`.

• Error: Command failed with exit code 1: docker ps

  cause Docker is not running or not installed, which is required for features like local Atlas deployments.
  fix Ensure Docker Desktop is installed and running on your system. Check Docker installation with `docker info`.

• Tool execution error: Insufficient permissions to perform write operation.

  cause The MCP server is running in read-only mode, or the MongoDB user connected by the server lacks the necessary write privileges.
  fix If write operations are intended, ensure the server is not started with the `readOnly: true` option. Verify the MongoDB user associated with the connection string has the required write roles (e.g., `readWrite` on the target database).

Warnings

• breaking Version 2 of `mongodb-mcp-server` will introduce breaking changes for programmatic 'library usage'. Users importing symbols directly for custom server implementations will need to adapt their code.
  Fix: Review the official V2 release notes and migration guide upon release. Adjust programmatic imports and API calls as specified.
• gotcha The server requires a MongoDB connection string or Atlas API credentials to start and function. Without proper configuration, the server will not launch. Docker is also a prerequisite for using local Atlas deployment tools.
  Fix: Ensure `MONGODB_URI` environment variable is set, or provide Atlas API credentials (`ATLAS_CLIENT_ID`, `ATLAS_PRIVATE_KEY`). For local Atlas tools, ensure Docker is installed and running.
• gotcha By default, the server may operate in read/write mode. Destructive operations like `delete-many`, `drop-collection`, and `drop-database` require explicit confirmation. To prevent unintended modifications, always consider starting the server in read-only mode, especially during initial exploration.
  Fix: Set the `readOnly` configuration option to `true` when starting the server (`--read-only` CLI flag or `readOnly: true` in config). Implement strict MongoDB user permissions for the provided connection string to limit AI agent access.
• gotcha Queries performed by AI agents might return excessively large result sets, consuming significant resources.
  Fix: Configure the `maxDocumentsPerQuery` option to limit the number of documents returned by a single query. Utilize the Performance Advisor tools exposed by the MCP server to identify and optimize slow queries and improve indexing.

Install

• npm install mongodb-mcp-server npm
• yarn add mongodb-mcp-server yarn
• pnpm add mongodb-mcp-server pnpm

Imports

• startServer

  import { startServer } from 'mongodb-mcp-server';

  Primary function for programmatically starting the MCP server. Most common usage is via `npx` or AI client configuration, but programmatic control is available.
• Config
  wrong:

  import { Config } from 'mongodb-mcp-server';

  correct:

  import { type Config } from 'mongodb-mcp-server';

  Represents the server's configuration interface, useful for type-checking when creating custom configurations. Imported as a type.
• Server

  import { Server } from 'mongodb-mcp-server';

  The underlying class for the Model Context Protocol server. While `startServer` is typically used for quick setup, this class can be instantiated for more advanced programmatic control over the server lifecycle and custom tool integration.

Quickstart

This quickstart demonstrates how to programmatically start the MongoDB MCP Server, configure it with a connection string, and handle graceful shutdowns. It also mentions the easier CLI-based setup.

import { startServer } from 'mongodb-mcp-server';

// To run the server programmatically, you must provide a MongoDB connection string.
// This can be via environment variables (MONGODB_URI, ATLAS_CLIENT_ID, ATLAS_PRIVATE_KEY)
// or passed directly in the configuration object.

// Ensure you have a MongoDB connection string set as an environment variable
// or replace process.env.MONGODB_URI with your actual connection string.
// For Atlas API credentials, set ATLAS_CLIENT_ID and ATLAS_PRIVATE_KEY.

const connectionString = process.env.MONGODB_URI ?? 'mongodb://localhost:27017/mcp-db';

const serverConfig = {
  connectionString: connectionString,
  port: 3000,
  readOnly: false, // Set to true to disable write operations
  logLevel: 'info' // 'debug', 'info', 'warn', 'error'
};

async function main() {
  try {
    console.log('Starting MongoDB MCP Server...');
    const server = await startServer(serverConfig);
    console.log(`MongoDB MCP Server listening on port ${serverConfig.port}`);

    // Example: Graceful shutdown
    process.on('SIGINT', async () => {
      console.log('SIGINT received, shutting down server...');
      await server.stop();
      process.exit(0);
    });
    process.on('SIGTERM', async () => {
      console.log('SIGTERM received, shutting down server...');
      await server.stop();
      process.exit(0);
    });
  } catch (error) {
    console.error('Failed to start MongoDB MCP Server:', error);
    process.exit(1);
  }
}

main();

// Alternative quick setup via CLI (recommended for initial setup):
// npx mongodb-mcp-server setup
// This command guides you through configuration and starts the server.