Skip to main content
Glama
mongodb36-mcp-server

mongodb36-mcp-server

by linzi007

MongoDB 3.6+ MCP Server

License: MIT Node.js Version MongoDB Version

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.

Features

  • āœ… 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

Installation

Prerequisites

  • Node.js >= 14.0.0

  • MongoDB 3.6 or higher

  • Access to a MongoDB instance

Install from npm

npm install -g mongodb36-mcp-server

Install from source

git clone https://github.com/linzi007/mongodb36-mcp-server.git
cd mongodb36-mcp-server
npm install
chmod +x index.js

Configuration

This server requires environment variables to be set. No default values are provided to ensure secure and explicit configuration.

Required Environment Variables

Variable

Description

Example

MONGODB_CONNECTION_STRING

MongoDB connection URI

mongodb://localhost:27017

MONGODB_DB_NAME

Database name to use

myDatabase

Setting Environment Variables

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=myDatabase

Windows (PowerShell):

$env:MONGODB_CONNECTION_STRING="mongodb://localhost:27017"
$env:MONGODB_DB_NAME="myDatabase"

Usage

Claude Desktop Configuration

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"
      }
    }
  }
}

Option 2: Using local installation

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": ["/absolute/path/to/mongodb36-mcp-server/index.js"],
      "env": {
        "MONGODB_CONNECTION_STRING": "mongodb://localhost:27017",
        "MONGODB_DB_NAME": "myDatabase"
      }
    }
  }
}

Option 3: Using GitHub repository directly

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "github:linzi007/mongodb36-mcp-server"],
      "env": {
        "MONGODB_CONNECTION_STRING": "mongodb://localhost:27017",
        "MONGODB_DB_NAME": "myDatabase"
      }
    }
  }
}

Running Directly

MONGODB_CONNECTION_STRING="mongodb://localhost:27017" \
MONGODB_DB_NAME="myDatabase" \
node index.js

Available Tools

The server provides the following MCP tools:

1. list_collections

List all collections in the database.

Example:

List all collections in the database

2. find

Find 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 5

3. find_one

Find 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"

4. count

Count 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"

5. aggregate

Run 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

Security Considerations

Connection String Security

  • āš ļø 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

Network Security

  • šŸ”’ 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

Best Practices

  1. Use read-only credentials when possible

  2. Limit database access to only required collections

  3. Monitor query performance to prevent resource exhaustion

  4. Set connection limits in MongoDB

  5. Use separate databases for development and production

Development

Project Structure

mongodb36-mcp-server/
ā”œā”€ā”€ index.js          # Main server implementation
ā”œā”€ā”€ package.json      # Package configuration
ā”œā”€ā”€ README.md         # This file
ā”œā”€ā”€ LICENSE           # MIT License
└── .gitignore        # Git ignore rules

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Troubleshooting

Error: MONGODB_CONNECTION_STRING environment variable is required

Solution: Set the MONGODB_CONNECTION_STRING environment variable before running the server.

Error: Failed to connect to MongoDB

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

Error: Database not found

Solution: Ensure the database name in MONGODB_DB_NAME exists or will be created on first write.

Examples

Basic Query Example

// 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
}

Aggregation Example

// 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" }
      }
    }
  ]
}

Compatibility

MongoDB Versions

  • āœ… 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 Versions

  • āœ… Node.js 14.x

  • āœ… Node.js 16.x

  • āœ… Node.js 18.x

  • āœ… Node.js 20.x

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Support


Made with ā¤ļø for the AI and MongoDB communities

Available Tools

5 tools
aggregateC

Run an aggregation pipeline

Inputs: pipeline (required), collection (required).

countA

Count documents in a collection

Inputs: collection (required), filter.

findC

Find documents in a collection

Inputs: collection (required), limit, filter.

find_oneB

Find a single document in a collection

Inputs: collection (required), filter.

list_collectionsA

List all collections in the database

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    Five tools is well-scoped for a read-only MongoDB query server. Each tool covers a distinct core operation without redundancy or bloat.

    Completeness2/5

    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.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to interact with MongoDB databases through a complete suite of CRUD operations, administrative tasks, and index management tools. It supports database and collection handling, aggregation pipelines, and comprehensive server monitoring via the Model Context Protocol.
      208 PyPI
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact natively with MongoDB databases, including schema discovery, CRUD operations, aggregation pipelines, and index management via natural language.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with MongoDB databases through natural language, supporting document CRUD, aggregation, collection listing, and statistics.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to interact with MongoDB databases and MongoDB Atlas, supporting read-only and write operations, Atlas cluster management, and data exploration.
      145,421 npm
      Apache 2.0