Hub Mongodb

Hub Mongodb is an MCP server that connects AI assistants to MongoDB databases and MongoDB Atlas clusters, enabling natural language queries, schema exploration, and data analysis. This MCP bridge allows language models to inspect collections, run aggregation pipelines, and retrieve documents from MongoDB instances while maintaining configurable access controls including read-only mode for safe production database access.

When to Use This MCP Server

Connect this server when...

• You need AI-assisted querying and analysis of MongoDB collections using natural language rather than writing raw queries
• Your application data lives in MongoDB Atlas or self-hosted MongoDB and you want conversational database exploration
• You are debugging data issues and need to quickly inspect document structures, indexes, and collection statistics
• You want to build aggregation pipelines interactively with AI guidance for complex data transformation tasks
• Your team needs a safe way to give AI assistants read-only access to production MongoDB data for reporting

Consider alternatives when...

• Your data lives in a relational database like PostgreSQL or MySQL, which have their own dedicated MCP servers
• You need real-time change stream processing rather than query-based data access
• You require bulk data export or ETL operations that go beyond individual query execution

Quick Start

Copy
# .mcp.json configuration
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
      }
    }
  }
}

Connection setup:

1. Ensure Node.js 18+ is installed on your system
2. Obtain your MongoDB connection string (from Atlas dashboard or your local instance)
3. For Atlas: whitelist your IP address in Network Access settings
4. Add the configuration above to your .mcp.json with your connection string
5. Restart your MCP client to connect

Example tool usage:

# Explore database schema
> What collections exist in this database and what do their document schemas look like?

# Query documents
> Find the 10 most recent orders where the total exceeds $100

# Run aggregation pipeline
> Group all users by country and show the average order value per country

Core Concepts

Concept	Purpose	Details
Connection String	Database targeting	Standard MongoDB URI format specifying host, port, authentication, and default database
Read-Only Mode	Safety control	Restricts the MCP server to read operations only, preventing any document modifications or deletions
Collections	Document containers	MongoDB collections hold groups of BSON documents with flexible schemas that can be queried and aggregated
Aggregation Pipeline	Data transformation	Multi-stage processing pipeline for filtering, grouping, sorting, and reshaping document data
Atlas Integration	Cloud database access	Native support for MongoDB Atlas clusters with TLS, authentication, and replica set connectivity

Architecture:

+------------------+       +------------------+       +------------------+
|  MongoDB         |       |  MongoDB MCP     |       |  AI Assistant    |
|  Database/Atlas  |<----->|  Server (npx)    |<----->|  (Claude, etc.)  |
|  (mongod/Atlas)  | driver|  stdio transport  | stdio |                  |
+------------------+       +------------------+       +------------------+
        |
        v
+--------------------------------------------------+
|  Databases > Collections > Documents > Indexes    |
+--------------------------------------------------+

Configuration

Parameter	Type	Default	Description
MDB_MCP_CONNECTION_STRING	string	(required)	MongoDB connection URI including host, credentials, and database name
--readOnly	flag	false	Restricts server to read-only operations, preventing writes, updates, and deletes
--database	string	(from URI)	Override the default database specified in the connection string
--maxPoolSize	integer	10	Maximum number of concurrent connections maintained in the connection pool
--timeout	integer	30000	Query timeout in milliseconds to prevent long-running operations from blocking

Best Practices

1. Always enable read-only mode for production databases. Pass the --readOnly flag when connecting to any production database. This prevents the AI assistant from accidentally modifying or deleting documents. Even if you trust the AI's intentions, read-only mode provides an essential safety net against malformed queries.

2. Use dedicated database users with minimal permissions. Create a MongoDB user specifically for MCP server access with only the read role on the necessary databases. Do not reuse application-level credentials or admin accounts. This limits the potential impact of credential exposure.

3. Specify the database in your connection string. Include the database name directly in the connection URI rather than relying on auto-detection. This ensures the AI assistant connects to the correct database immediately and avoids confusion when the MongoDB instance hosts multiple databases.

4. Set query timeouts to prevent runaway operations. MongoDB aggregation pipelines on large collections can consume significant resources. Configure the --timeout parameter to automatically cancel queries that exceed a reasonable duration, protecting your database performance for other consumers.

5. Index your frequently queried fields. Before connecting the MCP server, ensure your MongoDB collections have appropriate indexes for the types of queries the AI will run. Without indexes, queries on large collections will perform collection scans that are slow and resource-intensive.

Common Issues

"MongoNetworkError: connection refused" on startup. Verify that your MongoDB instance is running and accessible at the host and port specified in your connection string. For Atlas clusters, ensure your current IP address is whitelisted in Network Access settings. Check that the connection string uses the correct protocol (mongodb:// or mongodb+srv://).

"Authentication failed" when connecting to Atlas. Ensure the username and password in your connection string are for a database user (created in Database Access), not your Atlas account credentials. URL-encode any special characters in the password. Verify the user has the correct database roles assigned.

Aggregation queries return empty results unexpectedly. Check the collection name for case sensitivity, as MongoDB collection names are case-sensitive. Verify field names in your query match the actual document schema by first asking the AI to show a sample document. Also ensure the database in the connection string contains the target collection.