Verified MCP server: MongoDB
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The MongoDB MCP server lets an AI assistant query your MongoDB databases in plain English: list databases and collections, describe a schema, run a find or an aggregation, count documents, read indexes, and explain a query plan. It is MongoDB's own package, published from the mongodb-js organization under Apache-2.0, and it is one of the busiest database servers in the MCP ecosystem. We ran it rather than trusting the README: booted it with npx over stdio exactly as MongoDB's Quick Start shows, enumerated every tool the running process offers, and kept the raw output, including the exact errors it returns when the connection string is wrong. Two things that capture proved and no README states plainly: the recommended --readOnly flag cuts the tool list from 25 to 16 by hiding every write tool, and the Atlas management tools do not appear at all unless you supply Atlas API credentials. Both counts are ours, from the same session. [1][3][6]
Verification
Method
We spawned the server with npx over stdio using MongoDB's own --readOnly example, completed the MCP initialize handshake at protocol version 2025-06-18, called tools/list, and made one real tool call. The tool table below is that response, word for word. This Mac runs no MongoDB server and no Docker, and no Atlas cluster was available, so MDB_MCP_CONNECTION_STRING was set to an obvious placeholder host: enough to boot the server and enumerate what it offers, not enough to reach a database. The one tool call came back with the server's own connection error, printed below, so an authenticated call is still pending credentials. The same session ran six more probes to capture the errors in the troubleshooting section. Note that this server prints nothing to stderr at startup: the banner below arrived over MCP as notifications/message, which is where its log lives.
Startup banner
[server]: Detected a MongoDB connection string in the configuration, trying to connect...
[server]: Server with version 1.14.0 started with transport StdioServerTransport and agent runner {"name":"getroutines-mcp-verifier","version":"1.0.0","title":"unknown"}One real tool call
tools/call list-databases {}The configured connection string is not valid. Please check the connection string and confirm it points to a valid MongoDB instance.
Real lines from the captured result: enough to prove the call answered.
Tools
The server answered tools/list with 16 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| aggregate-dbdatabase*pipeline*responseBytesLimit | Run an aggregation against a MongoDB database |
| aggregatedatabase*collection*pipeline*responseBytesLimit | Run an aggregation against a MongoDB collection |
| collection-indexesdatabase*collection* | Describe the indexes for a collection |
| collection-schemadatabase*collection*sampleSizeresponseBytesLimit | Describe the schema for a collection |
| collection-storage-sizedatabase*collection* | Gets the size of the collection |
| connectconnectionString* | Connect to a MongoDB instance. The config resource captures if the server is already connected to a MongoDB cluster. If the user has configured a connection string or has previously called the connect tool, a connection is already established and there's no need to call this tool unless the user has explicitly requested to switch to a new MongoDB cluster. |
| countdatabase*collection*query | Gets the number of documents in a MongoDB collection using db.collection.count() and query as an optional filter parameter |
| db-statsdatabase* | Returns statistics that reflect the use state of a single database |
| explaindatabase*collection*method*verbosity | Returns statistics describing the execution of the winning plan chosen by the query optimizer for the evaluated method |
| exportdatabase*collection*exportTitle*exportTarget*jsonExportFormat | Export a query or aggregation results in the specified EJSON format. |
| finddatabase*collection*filterprojectionlimitsortresponseBytesLimit | Run a find query against a MongoDB collection |
| list-collectionsdatabase* | List all collections for a given database |
| list-databases | List all databases for a MongoDB connection |
| mongodb-logstypelimit | Returns the most recent logged mongod events |
| list-knowledge-sources | List available data sources in the MongoDB Assistant knowledge base. Use this to explore available data sources or to find search filter parameters to use in search-knowledge. |
| search-knowledgequery*limitdataSources | Search for information in the MongoDB Assistant knowledge base. This includes official documentation, curated expert guidance, and other resources provided by MongoDB. Supports filtering by data source and version. |
Parameters marked with * are required.
Setup
Copy the block for the app you use. Each one is the configuration this server was verified with.
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"MongoDB": {
"command": "npx",
"args": [
"-y",
"mongodb-mcp-server@latest",
"--readOnly"
],
"env": {
"MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net/myDatabase"
}
}
}
}Paste your own connection string, then quit and reopen Claude Desktop. Keep the --readOnly flag: MongoDB ships it in every example, and it is what stops an assistant from writing to your data. This is the exact shape we verified, and the connection string above is the placeholder we booted the server with. [8][6]
One command in your terminal:
claude mcp add --env MDB_MCP_CONNECTION_STRING="mongodb+srv://user:pass@cluster.mongodb.net/myDatabase" --transport stdio mongodb -- npx -y mongodb-mcp-server@latest --readOnly
Everything after the double dash is the exact command Claude Code will run. The --transport flag sits between the --env pair and the server name on purpose: a name placed straight after --env is read as another KEY=value pair and rejected. [9]
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"MongoDB": {
"command": "npx",
"args": [
"-y",
"mongodb-mcp-server@latest",
"--readOnly"
],
"env": {
"MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net/myDatabase"
}
}
}
}Cursor picks the file up on restart. The one-click Install in Cursor badge in MongoDB's README sets the command but not the connection string, so add the env block yourself either way. Treat that file the way you treat any file with a database password in it: it is plain text on disk, so keep it out of a repository you push. [10][6]
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name MongoDB Command npx Arguments -y mongodb-mcp-server@latest --readOnly Environment Variables MDB_MCP_CONNECTION_STRING mongodb+srv://user:pass@cluster.mongodb.net/myDatabase
The Arguments field splits on spaces, so keep it to exactly those three words. Your connection string contains a password, so it goes in Environment Variables, never in Arguments. Click Test Connection first: with --readOnly in place a working server answers with sixteen tools. [11][6]
No terminal needed
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tools are available to your AI in chat and in scheduled routines. The only thing you have to fetch first is a MongoDB connection string.
01
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
On Atlas, open your cluster, click Connect, choose Drivers, and copy the string that starts with mongodb+srv://. Replace the placeholder password with the real one for that database user. If your database runs on this Mac instead, the string is usually mongodb://localhost:27017/yourDatabase. Give the user read-only rights if you can: this page uses the read-only setup throughout.
03
Back in Routines, click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
04
The form opens in URL (SSE/HTTP) mode. Switch it to Command (stdio): this server is a command, not a web address. Name: MongoDB. Command: npx. Arguments: -y mongodb-mcp-server@latest --readOnly, exactly those three words.
05
In Environment Variables add MDB_MCP_CONNECTION_STRING with the string you copied. Click Test Connection: Routines starts the server without saving it and reports how many tools it found, sixteen with --readOnly in place. Then click Add Server.
06
The tools work in chat right away: ask which collections exist, or what a document looks like. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
Every Monday at 9:00, count the documents in every collection in my production database, compare the counts with the ones in data-health.md from last week, and rewrite that file with this week's numbers and a note on anything that moved more than 20 percent.
Every weekday at 8:00, find the users created in the last 24 hours in my app database, group them by signup source and plan, and save the counts with a one-line comment as signups.md in my Notes folder.
Every Friday at 15:00, list the indexes on my orders collection, run explain on the three queries I use most, and write anything that is doing a full collection scan to index-review.md with the query that caused it.
Troubleshooting
Real errors captured during the verification run, printed exactly as the server returned them.
What you see
[server]: Failed to connect to MongoDB instance using the connection string from the config: querySrv ENOTFOUND _mongodb._tcp.cluster0.placeholder.mongodb.net
The fix
That line is the server's own log, which it sends over MCP as a notifications/message rather than printing to stderr. The tool call itself answers with a different string: "The configured connection string is not valid. Please check the connection string and confirm it points to a valid MongoDB instance." The server connects lazily, so a bad connection string does not stop it from starting or from listing its tools; you only find out on the first real call. This is exactly what our run produced, because we booted it with a placeholder host on purpose. ENOTFOUND on a name beginning with _mongodb._tcp means the mongodb+srv:// hostname does not resolve, so check the cluster address for a typo, and check that your network can reach it. A wrong password gives a different message, an authentication failure rather than a DNS one.
What you see
You need to connect to a MongoDB instance before you can access its data.
The fix
You started the server with no connection string at all, which is allowed: it boots and lists all its tools anyway. Either set MDB_MCP_CONNECTION_STRING (in the env block, or in Environment Variables in Routines) and restart, or ask the assistant to call the connect tool with a connection string for this session only.
What you see
[server]: Failed to connect to MongoDB instance using the connection string from the config: connect ECONNREFUSED <ip address>:27017
The fix
The address resolved but nothing is listening on port 27017, which is what a Mac with no local MongoDB running answers. Start your local mongod or your Docker container first, or point the connection string at your Atlas cluster instead. The server redacts the address itself, which is why the message reads <ip address> rather than a number.
What you see
MCP error -32602: Tool drop-database not found
The fix
That is the --readOnly flag doing its job. With the flag on, the server publishes 16 tools and every create, update and delete tool is absent, so the assistant cannot even see them; we counted 25 tools in the same session with the flag removed. If you genuinely need writes, drop --readOnly from the arguments and restart, and understand that you have just handed an assistant delete-many and drop-collection.
What you see
MCP error -32602: Tool atlas-list-projects not found
The fix
The Atlas management tools are only registered when Atlas API credentials are present. Set MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET from an Atlas Service Account and restart the server, and they appear alongside the database tools. Our run had none, which is why the table on this page is the database side only.
What you see
MCP error -32602: Input validation error: Invalid arguments for tool find: Invalid input: expected string, received undefined at database Invalid input: expected string, received undefined at collection
The fix
The assistant called find without naming a database and a collection, both of which are required. It is usually a sign the model is guessing at your data layout: ask it to run list-databases and list-collections first, then repeat the question. We triggered this one on purpose by sending find with no arguments.
The fix
The npx command belongs to Node.js. If Node is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again.
FAQ
It is a small program from MongoDB that sits between an AI assistant and your MongoDB databases and speaks the Model Context Protocol. Once connected, an assistant such as Claude can list databases and collections, describe a collection's schema and indexes, run find queries and aggregations, count documents, read recent mongod events, and explain a query plan. It runs as a local process on your Mac and talks to your AI app over stdio, or over Streamable HTTP if you opt into it. [6][3]
Started the way MongoDB recommends, with --readOnly, the running server exposes 16 tools: querying (find, aggregate, aggregate-db, count, explain, export), structure (list-databases, list-collections, collection-schema, collection-indexes, collection-storage-size, db-stats, mongodb-logs), the connection itself (connect), and MongoDB's documentation assistant (search-knowledge, list-knowledge-sources). The table above is that live tools/list output, word for word. Remove --readOnly and the same server publishes 25: the nine extra are create-collection, create-index, insert-many, update-many, delete-many, drop-collection, drop-database, drop-index and rename-collection. Both counts come from our own run.
It needs a MongoDB connection string, not an API key: MDB_MCP_CONNECTION_STRING, pointing either at a database on your own Mac or at an Atlas cluster. The Atlas management tools are a separate matter and need an Atlas Service Account, MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET. Neither is required to start the server: it boots and lists its tools with nothing set, and only fails when a tool actually needs the database. [6]
The defaults are careful, and three of them are worth knowing. Every example MongoDB publishes carries --readOnly, which we verified removes all nine write tools from the list rather than merely blocking them. Server-side JavaScript operators such as $where and $function are disabled by default. The destructive tools that do exist ask for confirmation only if your client supports MCP elicitation, so a client without it may run them straight through. Two more things to weigh: telemetry is enabled by default and MDB_MCP_TELEMETRY=disabled turns it off, and we watched the running server send telemetry events during our capture. The HTTP transport is opt-in and MongoDB itself says it is not production-safe without your own auth layer. The strongest control is still the connection string: give the assistant a database user with read-only rights. [6]
No. In Routines you fill in the fields in Settings and click Test Connection; the walkthrough above shows every click, including where the connection string goes. Claude Desktop needs a small JSON file edited once. Only Claude Code is terminal-first by nature. [11][8]
On the day we ran this, npm served 1.14.0 as latest, published 2026-07-14, and that is the version this page describes. The project's main branch already reads 2.0.0, bumped in a release commit merged 2026-07-31 that had not reached npm yet, so a 2.x release is imminent and mongodb-mcp-server@latest will pick it up the moment it lands. That is the argument for pinning an exact version in anything you rely on, rather than trusting @latest: 78 versions have been published, including alpha and prerelease channels. [1][4][5]
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor and Routines all can, and the exact config for each is above. MongoDB's README also documents VS Code, Windsurf, GitHub Copilot CLI and OpenCode, plus an official Docker image if you would rather not use npx. The server is the same everywhere; only the place you paste the config differs. Be careful with community packages of similar name on npm, such as @pash1986/mongodb-mcp-server or @harryelv/mongodb-mcp-server: none of them are MongoDB's, and the official one is simply mongodb-mcp-server. [6][1][7]
Sources
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
Latest version 1.14.0, published 2026-07-14, license Apache-2.0, repository mongodb-js/mongodb-mcp-server. 78 published versions across the latest, pre, prerelease and alpha channels.
[2]
[3]
1,091 stars, Apache-2.0, not archived, last push 2026-07-31, created 2025-04-04, per the GitHub API.
[4]
The version field on main reads 2.0.0, ahead of the 1.14.0 that npm serves as latest.
[5]
Merged 2026-07-31; the commit says the new version will be published to npm once merged, which had not happened at access time.
[6]
Quick Start configs, the safety notice that every example ships --readOnly, the full MDB_MCP_ option table including READ_ONLY, TELEMETRY, DISABLE_SERVER_SIDE_JS and CONFIRMATION_REQUIRED_TOOLS, the Docker image, and the HTTP transport warning.
[7]
Community lookalikes with no MongoDB affiliation: @pash1986/mongodb-mcp-server, @harryelv/mongodb-mcp-server, @henrik3/mongodb-mcp-server, mongo-mongoose-mcp, @krazor/mongodb-mcp, @iflow-mcp/mongodb-mcp-server.
[8]
The Claude Desktop config file location and the mcpServers shape, linked from this server's README.
[9]
The claude mcp add syntax for local stdio servers, the --env flag, and the warning about placing the server name straight after --env.
[10]
The mcp.json shape and the two file locations, ~/.cursor/mcp.json and .cursor/mcp.json.
[11]
How Routines runs one-click OAuth connectors and any MCP server.
This page describes MongoDB as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. The reports it writes stay markdown files on your Mac, and there is no cloud bill. Download Routines