Provides tools for interacting with a MongoDB database, enabling listing collections, finding documents, counting documents, and running aggregation pipelines.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mongodb36-mcp-server List all collections in the database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server implementation for MongoDB 3.6 and above. This server enables AI assistants like Claude to interact with MongoDB databases through a standardized interface.
ā MongoDB 3.6+ Compatible: Works with MongoDB 3.6 and all newer versions
š§ Standard MCP Protocol: Implements the Model Context Protocol specification
š ļø Essential Operations: List collections, find documents, count, and aggregations
š Environment-based Configuration: Secure configuration through environment variables
š¦ Zero Default Values: Requires explicit configuration for security
Related MCP server: MongoDB MCP Server
Node.js >= 14.0.0
MongoDB 3.6 or higher
Access to a MongoDB instance
npm install -g mongodb36-mcp-servergit clone https://github.com/linzi007/mongodb36-mcp-server.git
cd mongodb36-mcp-server
npm install
chmod +x index.jsThis server requires environment variables to be set. No default values are provided to ensure secure and explicit configuration.
Variable | Description | Example |
| MongoDB connection URI |
|
| Database name to use |
|
Linux/macOS:
export MONGODB_CONNECTION_STRING="mongodb://localhost:27017"
export MONGODB_DB_NAME="myDatabase"Windows (Command Prompt):
set MONGODB_CONNECTION_STRING=mongodb://localhost:27017
set MONGODB_DB_NAME=myDatabaseWindows (PowerShell):
$env:MONGODB_CONNECTION_STRING="mongodb://localhost:27017"
$env:MONGODB_DB_NAME="myDatabase"Add this server to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": ["-y", "mongodb36-mcp-server"],
"env": {
"MONGODB_CONNECTION_STRING": "mongodb://localhost:27017",
"MONGODB_DB_NAME": "myDatabase"
}
}
}
}{
"mcpServers": {
"mongodb": {
"command": "node",
"args": ["/absolute/path/to/mongodb36-mcp-server/index.js"],
"env": {
"MONGODB_CONNECTION_STRING": "mongodb://localhost:27017",
"MONGODB_DB_NAME": "myDatabase"
}
}
}
}{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": ["-y", "github:linzi007/mongodb36-mcp-server"],
"env": {
"MONGODB_CONNECTION_STRING": "mongodb://localhost:27017",
"MONGODB_DB_NAME": "myDatabase"
}
}
}
}MONGODB_CONNECTION_STRING="mongodb://localhost:27017" \
MONGODB_DB_NAME="myDatabase" \
node index.jsThe server provides the following MCP tools:
list_collectionsList all collections in the database.
Example:
List all collections in the databasefindFind documents in a collection.
Parameters:
collection (required): Collection name
filter (optional): MongoDB query filter
limit (optional): Maximum number of documents (default: 10)
Example:
Find documents in the "users" collection where age > 25, limit 5find_oneFind a single document in a collection.
Parameters:
collection (required): Collection name
filter (optional): MongoDB query filter
Example:
Find one document in the "users" collection where email is "user@example.com"countCount documents in a collection.
Parameters:
collection (required): Collection name
filter (optional): MongoDB query filter
Example:
Count documents in the "orders" collection where status is "completed"aggregateRun an aggregation pipeline.
Parameters:
collection (required): Collection name
pipeline (required): Array of aggregation stages
Example:
Run aggregation on "sales" collection to group by product and sum quantitiesā ļø Never commit credentials to version control
ā Use environment variables for sensitive data
ā
Consider using MongoDB connection string with authentication: mongodb://username:password@host:port
ā
Use SSL/TLS for production: mongodb://host:port?ssl=true
š Ensure MongoDB instance is not exposed to the public internet
š Use firewall rules to restrict access
š Enable MongoDB authentication and authorization
š Use VPN or SSH tunneling for remote connections
Use read-only credentials when possible
Limit database access to only required collections
Monitor query performance to prevent resource exhaustion
Set connection limits in MongoDB
Use separate databases for development and production
mongodb36-mcp-server/
āāā index.js # Main server implementation
āāā package.json # Package configuration
āāā README.md # This file
āāā LICENSE # MIT License
āāā .gitignore # Git ignore rulesContributions are welcome! Please follow these steps:
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
Solution: Set the MONGODB_CONNECTION_STRING environment variable before running the server.
Possible causes:
MongoDB is not running
Incorrect connection string
Network firewall blocking connection
Authentication failure
Solution:
Verify MongoDB is running: mongo --version
Test connection: mongo "your-connection-string"
Check firewall settings
Verify credentials
Solution: Ensure the database name in MONGODB_DB_NAME exists or will be created on first write.
// In Claude Desktop, you can ask:
"Show me all users in the users collection"
// This will call the find tool:
{
"collection": "users",
"filter": {},
"limit": 10
}// In Claude Desktop, you can ask:
"Calculate the average order value by customer from the orders collection"
// This will call the aggregate tool:
{
"collection": "orders",
"pipeline": [
{
"$group": {
"_id": "$customer_id",
"avgOrderValue": { "$avg": "$total" }
}
}
]
}ā MongoDB 3.6.x
ā MongoDB 4.0.x
ā MongoDB 4.2.x
ā MongoDB 4.4.x
ā MongoDB 5.0.x
ā MongoDB 6.0.x
ā MongoDB 7.0.x
ā Node.js 14.x
ā Node.js 16.x
ā Node.js 18.x
ā Node.js 20.x
This project is licensed under the MIT License - see the LICENSE file for details.
Model Context Protocol - The protocol specification
MongoDB Node.js Driver - Official MongoDB driver
Anthropic - For developing Claude and the MCP specification
š Documentation
š Issue Tracker
š¬ Discussions
Made with ā¤ļø for the AI and MongoDB communities
Run an aggregation pipeline
| Name | Required | Description | Default |
|---|---|---|---|
| pipeline | Yes | Aggregation pipeline stages | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of behavioral disclosure. It only states the operation type without revealing whether results are returned as a stream, a single document, or aggregated values, and it omits side effects, authorization needs, or performance considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and direct, but it is under-specified rather than efficiently informative. It conveys the core action in one clause but provides no additional structured detail that would help an agent use the tool correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain return behavior, pipeline expectations, and usage context. It does none of that, so the agent is left without enough information to confidently predict the outcome of invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters with descriptions, so the schema carries the semantic weight. The description adds no parameter-level meaning, which is acceptable given the 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation, running an aggregation pipeline, which is distinct from sibling tools like find, count, and list_collections. It is clear about the action and resource, though it does not explicitly contrast itself with siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use aggregate versus find, count, or list_collections. The description does not mention use cases, limitations, or alternatives, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count documents in a collection
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Query filter (MongoDB query syntax) | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the core operation (counting documents) and implies a read-only action, but it does not mention how the optional filter affects the count, whether the count is exact or estimated, or what the response format is. This is a moderate but not severe gap for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence containing only the essential information. Every word earns its place and there is no filler, making it highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool, the description plus schema is mostly sufficient to select and invoke it. The sibling context and the simple operation cover most needs. However, with no output schema or annotations, it would be slightly stronger to explicitly state that it returns a count and that omitting the filter counts all documents in the collection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter meaning beyond what the schema already provides: 'collection' and 'filter' are both documented, with the filter explicitly described as MongoDB query syntax. The description's 'in a collection' mirrors the existing collection parameter without adding insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Count'), a resource ('documents in a collection'), and clearly identifies the operation. It is distinct from siblings like find (returns documents) and aggregate (pipeline processing), so an agent can tell it apart without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use count versus aggregate or find, nor any mention of exclusions or alternative tools. Sibling tools overlap in capability (aggregate can also count), and the description does not help an agent choose between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find documents in a collection
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of documents to return | |
| filter | No | Query filter (MongoDB query syntax) | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only restates the basic purpose. It does not explain that the filter is optional, that limit defaults to 10, what the return shape looks like, or whether the operation is read-only. The description is not misleading, but it provides almost no behavioral detail beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no filler, which is structurally clean. However, it is under-specified for a tool with three parameters and no annotations; conciseness edges into incompleteness. The sentence earns its place but does not carry enough useful information to be highly rated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, but with no output schema and no annotations, the description must cover return behavior and selection context. It only states the basic purpose, leaving default-limit behavior, optional filter semantics, and differences from find_one or aggregate unaddressed. This is insufficient for confident tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 even with no parameter details in the description. The description only mentions the collection as the target and does not add meaning to filter or limit beyond what the schema already documents. This meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Find') and a resource ('documents in a collection'), so an agent can tell it returns documents. However, it does not explicitly differentiate from the sibling find_one, and only the plural 'documents' hints that it returns multiple records. It is clear but lacks overt sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus find_one, count, or aggregate. Sibling tools are listed but never referenced, and no conditions, exclusions, or preferred alternatives are mentioned. An agent must infer usage entirely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a single document in a collection
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Query filter (MongoDB query syntax) | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does not disclose key edge-case behavior: what happens when no document matches (null vs error), which document is returned when multiple match (e.g., natural order), or whether invalid Mongo query syntax errors out. These are important traits for an agent invoking this tool on unknown data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with zero filler words; the verb comes first and the resource is immediately clear. It is concise without being bloated, though a short second sentence on return behavior would have improved it without harming brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with 100% schema coverage, the description is minimally adequate. However, with no output schema and no annotations, the description should have disclosed the return value shape (document vs null) and multi-match behavior to be complete; these gaps are the main deficit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% ā 'filter' documents MongoDB query syntax and 'collection' is described as the collection name ā so the schema already carries the parameter meaning. The description adds no parameter-level detail beyond this, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find') and resource ('a single document in a collection'). The qualifier 'single' usefully differentiates it from the sibling 'find', which presumably returns multiple documents, and 'count'/'aggregate'. However, it does not name the sibling explicitly and is close to a light restatement of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is only implied through the word 'single', suggesting the tool is for retrieving exactly one matching document. There is no explicit when-to-use guidance, no mention of alternatives like 'find' for multiple results or 'count' for counting matches, and no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all collections in the database
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly conveys a read-only enumeration behavior with no visible side effects. It does not mention edge cases like system collections or exact return shape, but for such a simple operation the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundant wording. Every word contributes meaning, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only listing tool, the description is largely complete: it states the action, the resource, and the scope. The only minor gap is that it does not specify the return format, though 'list all collections' conventionally implies a list of collection names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to add beyond what the empty schema conveys. This matches the baseline of 4 for parameter-less tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('collections') with a clear scope ('all in the database'). It also differentiates from sibling tools like find, count, and aggregate, which operate on documents inside collections rather than enumerating collections themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for database-level enumeration rather than document-level operations, but it does not explicitly state when to use it over the sibling tools. There is no mention of alternatives or conditions that would select a different tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0aggregatecountfindfind_onelist_collectionsScored across 5 tools
Find and find_one are similar but clearly separated by singular vs plural result intent. Count, aggregate, and list_collections each have distinct purposes, so an agent can reliably choose the right tool.
All tool names use lowercase snake_case and follow familiar MongoDB terminology. list_collections follows verb_noun while find, find_one, count, and aggregate are verb-only, but the naming is still predictable and readable.
Five tools is well-scoped for a read-only MongoDB query server. Each tool covers a distinct core operation without redundancy or bloat.
The tool set only supports reading and querying data; there are no create, update, or delete operations. As a general MongoDB server this is a significant gap, leaving agents unable to perform basic write workflows.
GibsonAI MCP server: manage your databases with natural language
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Query your org's data in natural language ā read-only MCP access to SQL, NoSQL, files & warehouses.
Interact with your Google Cloud Firestore resources using natural language commands.
