mcp-mongo-server

library2.0.2jsnpmunverified

MCP MongoDB Server (v2.0.2) is a Model Context Protocol (MCP) server that enables LLMs like Claude to interact with MongoDB databases. It provides tools for inspecting schemas, running queries and aggregations, and performing write operations (inserts, updates, index creation) with configurable read-only mode. Key differentiators include smart ObjectId conversion (auto/none/force), automatic schema inference, and collection name auto-completions for LLMs. Released on npm with active development, it supports the growing MCP ecosystem for AI-assisted database operations.

database

npm install mcp-mongo-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MCP-MONGO-SERVER

mcp-mongo-server

databasejavascriptv2.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mcp-mongo-server

✓ npx -y mcp-mongo-server mongodb://localhost:27017/database

✗ npx mcp-mongo-server

This is a CLI tool, not a library. Use npx to run without installing globally. Always provide a MongoDB URI as argument or via MCP_MONGODB_URI environment variable.

Starts the MCP MongoDB server in read-only mode. Shows how to run the CLI and configure an MCP client (like Claude Desktop) to connect.

npx -y mcp-mongo-server mongodb://user:pass@localhost:27017/mydb --read-only # Then configure your MCP client (e.g., Claude Desktop) with: # { # "mcpServers": { # "mongodb": { # "command": "npx", # "args": [ # "-y", # "mcp-mongo-server", # "mongodb://user:pass@localhost:27017/mydb" # ] # } # } # }

Debug

Known issues

breakingv2.0.0 changed the command name from mcp-mongo to mcp-mongo-server. Previous CLI invocations will break.

fix

Use npx -y mcp-mongo-server instead of npx mcp-mongo.

affects: <2.0.0

breakingv2.0.0 removed the --dry-run option; use --read-only instead.

fix

Replace --dry-run with --read-only in CLI arguments and MCP_MONGODB_DRY_RUN env var with MCP_MONGODB_READONLY.

affects: <2.0.0

gotchaIn default mode, write operations (insert, update, createIndex) are allowed. Ensure you use --read-only if you want to prevent modifications.

fix

Pass --read-only flag or set MCP_MONGODB_READONLY=true to restrict to read-only operations.

affects: >=2.0.0

gotchaObjectId handling is configurable but defaults to 'auto' mode. Documents with string _id fields may not be converted to ObjectId automatically in queries unless 'force' mode is set.

fix

Use --object-id-handler=force (CLI) or set MCP_MONGODB_OBJECTID_HANDLER=force to always convert string _id to ObjectId.

affects: >=2.0.0

deprecatedThe MCP_MONGODB_DRY_RUN environment variable was deprecated in v1.0.0 and removed in v2.0.0. Use MCP_MONGODB_READONLY instead.

fix

Replace MCP_MONGODB_DRY_RUN with MCP_MONGODB_READONLY=true in your environment configuration.

affects: <2.0.0

Errors

Common errors & fixes

Error: Missing required argument: uri

Running mcp-mongo-server without providing a MongoDB connection URI.

fix

Pass the URI as an argument: npx -y mcp-mongo-server mongodb://localhost:27017/mydb

MongoServerSelectionError: connect ECONNREFUSED ::1:27017

MongoDB server is not running or not reachable at the specified host and port.

fix

Start your MongoDB instance or verify the host/port in the URI. If using a different host (e.g., 127.0.0.1 vs localhost), specify it explicitly.

MongoParseError: Invalid connection string

MongoDB URI is malformed.

fix

Ensure the URI follows the standard mongodb://[user:pass@]host[:port]/database format. Escape special characters in password if present.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredCore MCP server SDK for tool registration and communication

mongodbrequiredOfficial MongoDB Node.js driver for database connections and operations

mongodb-query-parserrequiredParses and validates MongoDB query syntax used in tool arguments

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/kiliczsh/mcp-mongo-server ↗

packagemcp-mongo-server ↗

homepagehttps://github.com/kiliczsh/mcp-mongo-server ↗