mongodb-mcp

library1.0.4jsnpmunverified

A read-only Model Context Protocol (MCP) server for querying MongoDB databases, version 1.0.4, actively maintained. It exposes tools like list_databases, list_collections, list_indexes, run_aggregation, and run_aggregation_to_file via the MCP standard, allowing AI agents to inspect MongoDB schemas and run aggregation pipelines. Key differentiators: entirely read-only (rejects write stages $out, $merge), enforces a 50-second query timeout, and uses secondaryPreferred read preference for safety. Requires Node >=18 and a MongoDB connection string via MONGODB_URI environment variable. Published on npm, includes TypeScript types.

database

npm install mongodb-mcp

package ↗

INSTALL

IMPORT

SIG · MONGODB-MCP

mongodb-mcp

databasejavascriptv1.0.4

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.

Server

✓ import { Server } from '@modelcontextprotocol/sdk/server/index.js'

✗ import { Server } from '@modelcontextprotocol/sdk'

MCP SDK v1 requires explicit path to server/index.js for ES module imports.

MongoClient

✓ import { MongoClient } from 'mongodb'

✗ const MongoClient = require('mongodb').MongoClient

Using CommonJS require works, but ESM is recommended for TypeScript.

CallToolRequestSchema

✓ import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

Or use the shorthand from '@modelcontextprotocol/sdk/types' if exporting types.

Shows how to start the MongoDB MCP server via npx with a connection URI, and example configuration for Claude Desktop.

// Set MONGODB_URI environment variable before starting the server // Run: MONGODB_URI="mongodb://localhost:27017" npx mongodb-mcp // Or in a Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json): // { // "mcpServers": { // "mongodb": { // "command": "npx", // "args": ["mongodb-mcp"], // "env": { // "MONGODB_URI": "mongodb://localhost:27017/mydb" // } // } // } // }

Debug

Known issues

deprecatedThe 'run_aggregation_to_file' tool may be deprecated in future versions in favor of streaming results.

fix

Use 'run_aggregation' for smaller result sets, or monitor for alternative output methods.

affects: >=1.0.0

breakingMONGODB_URI environment variable must be set; server will crash if missing.

fix

Ensure MONGODB_URI is exported before running the server: export MONGODB_URI='mongodb://...'

affects: >=1.0.0

gotchaAggregation pipeline write stages ($out, $merge) are rejected; the tool is read-only.

fix

Do not include write stages in the pipeline array. Use run_aggregation for read-only queries.

affects: >=1.0.0

gotchaAggregation queries have a 50-second maxTimeMS limit; long-running queries will timeout.

fix

Optimize pipelines or use run_aggregation_to_file for large result sets to avoid timeout.

affects: >=1.0.0

Errors

Common errors & fixes

Error: MONGODB_URI environment variable is required

The MONGODB_URI environment variable is not set or is empty.

fix

Set the MONGODB_URI variable before running: export MONGODB_URI='mongodb://username:password@host:port/dbname'

Error: connect ECONNREFUSED ::1:27017

MongoDB server is not running or not accessible at the specified URI.

fix

Start mongod locally or correct the connection string in MONGODB_URI.

MongoServerError: $out is not allowed in this pipeline

The aggregation pipeline contains a write stage ($out or $merge), which is forbidden.

fix

Remove $out or $merge stages from the pipeline.

Error: Query exceeded maxTimeMS of 50000ms

Aggregation query took longer than 50 seconds.

fix

Optimize the pipeline, add indexes, or use run_aggregation_to_file to write results to a file.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredCore SDK for building MCP servers; provides the Server class and protocol handling.

mongodbrequiredOfficial MongoDB Node.js driver for connecting and querying MongoDB.

Agent activity

8 hits · last 30 days

node

Resources

packagemongodb-mcp ↗