playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

QueryNest (MongoDB) MCP server

Transforms MongoDB databases into conversational interfaces by automatically discovering collection schemas and generating optimized queries from natural language requests.
Back to servers
Setup instructions
Provider
niuzaishu
Release date
Aug 04, 2025
Stats
1 star
View on GitHub

QueryNest is a MongoDB multi-instance query service based on the MCP (Model Context Protocol). It provides intelligent database structure discovery, semantic analysis, and natural language query generation capabilities to make interacting with MongoDB databases easier and more intuitive.

Installation

Requirements

  • Python 3.8+
  • MongoDB 4.0+
  • Redis (optional, for caching)

Quick Start

Using uvx (Recommended)

The quickest way to start the service is using the uvx tool:

# Install uv tool (if not already installed)
pip install uv

# Start from the project directory (recommended)
cd /path/to/QueryNest
uvx --from . --no-cache querynest-mcp

# Or start from any location
uvx --from /path/to/QueryNest --no-cache querynest-mcp

Benefits of using uvx:

  • Automatically handles dependencies
  • No need to pre-install packages
  • Uses isolated execution environment
  • Automatically caches for faster subsequent starts

Manual Installation

  1. Clone the project
git clone https://github.com/niuzaishu/QueryNest.git
cd QueryNest
  1. Install dependencies
cd QueryNest
pip install -r requirements.txt
  1. Configure the service
# Copy the configuration template
cp config.example.yaml config.yaml

# Edit the configuration file (modify MongoDB connection strings based on your environment)
vim config.yaml  # or use your preferred editor
  1. Start the service
# Development mode (direct run)
python mcp_server.py --log-level DEBUG

# Production mode (using uvx, recommended)
uvx --from . --no-cache querynest-mcp

# Set configuration file path (if needed)
export QUERYNEST_CONFIG_PATH=/path/to/config.yaml

Docker Deployment

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop service
docker-compose down

Configuration

MCP Client Configuration

After starting the service, you can configure QueryNest in any AI client that supports the MCP protocol to enable intelligent database querying.

For MCP-compatible AI clients, here's an example configuration for QueryNest:

{
  "mcpServers": {
    "QueryNest": {
      "command": "uvx",
      "args": ["--from", "/path/to/QueryNest", "--no-cache", "querynest-mcp"],
      "cwd": "/path/to/QueryNest",
      "env": {
        "QUERYNEST_CONFIG_PATH": "/path/to/QueryNest/config.yaml",
        "QUERYNEST_LOG_LEVEL": "INFO"
      }
    }
  }
}

Windows configuration example:

{
  "mcpServers": {
    "QueryNest": {
      "command": "uvx",
      "args": ["--from", "C:\\path\\to\\QueryNest", "--no-cache", "querynest-mcp"],
      "cwd": "C:\\path\\to\\QueryNest",
      "env": {
        "QUERYNEST_CONFIG_PATH": "C:\\path\\to\\QueryNest\\config.yaml"
      }
    }
  }
}

MongoDB Instance Configuration

QueryNest supports flexible environment configurations. You can configure different types of instances based on your needs:

mongodb:
  instances:
    prod-main:
      name: "Production Main"
      environment: "prod"
      connection_string: "mongodb://admin:password@localhost:27017/admin"
      database: "prod_database"
      description: "Production environment main database"
      status: "active"
      tags: ["production", "primary"]
    
    crm-prod:
      name: "CRM Production"
      environment: "crm-prod"
      connection_string: "mongodb://crm_user:${CRM_DB_PASSWORD}@crm-db.company.com:27017/admin"
      database: "crm_database"
      description: "CRM system production database"
      status: "active"
      tags: ["crm", "production"]

Security Configuration

security:
  permissions:
    allowed_operations:
      - "find"
      - "count"
      - "aggregate"
      - "distinct"
    forbidden_operations:
      - "insert"
      - "update"
      - "delete"
  limits:
    max_documents: 1000
    query_timeout: 30
  data_masking:
    enabled: true
    sensitive_field_patterns:
      - "password"
      - "email"
      - "phone"

Environment Variables

QueryNest supports the following environment variables:

Environment Variable Description Default Value Example
QUERYNEST_CONFIG_PATH Configuration file path config.yaml /app/config.yaml
QUERYNEST_LOG_LEVEL Log level INFO DEBUG, INFO, WARNING, ERROR
QUERYNEST_MCP_TRANSPORT MCP transport method stdio stdio, http
QUERYNEST_MCP_HOST HTTP mode host address None 0.0.0.0
QUERYNEST_MCP_PORT HTTP mode port None 8000
MONGO_PROD_PASSWORD Production MongoDB password - your_password
MONGO_TEST_PASSWORD Test MongoDB password - your_password
MONGO_DEV_PASSWORD Development MongoDB password - your_password

Using MCP Tools

1. Discover Instances

Discover and list all available MongoDB instances.

{
  "name": "discover_instances",
  "arguments": {
    "include_health": true,
    "include_stats": true
  }
}

2. Discover Databases

List all databases in the specified instance.

{
  "name": "discover_databases",
  "arguments": {
    "instance_id": "prod-main",
    "include_collections": true,
    "exclude_system": true
  }
}

3. Analyze Collection

Analyze the structure and field information of a specified collection.

{
  "name": "analyze_collection",
  "arguments": {
    "instance_id": "prod-main",
    "database_name": "ecommerce",
    "collection_name": "users",
    "include_semantics": true,
    "include_examples": true,
    "rescan": false
  }
}

4. Manage Semantics

Manage business semantic information for fields.

{
  "name": "manage_semantics",
  "arguments": {
    "action": "batch_analyze",
    "instance_id": "prod-main",
    "database_name": "ecommerce",
    "collection_name": "users"
  }
}

5. Generate Query

Generate MongoDB queries based on natural language descriptions.

{
  "name": "generate_query",
  "arguments": {
    "instance_id": "prod-main",
    "database_name": "ecommerce",
    "collection_name": "orders",
    "query_description": "Find orders created today, sorted by amount in descending order",
    "query_type": "auto",
    "limit": 50
  }
}

6. Confirm Query

Execute the generated query and return results.

{
  "name": "confirm_query",
  "arguments": {
    "instance_id": "prod-main",
    "database_name": "ecommerce",
    "collection_name": "orders",
    "query_type": "find",
    "mongodb_query": {
      "filter": {"created_at": {"$gte": "2024-01-01T00:00:00Z"}},
      "sort": {"amount": -1},
      "limit": 50
    },
    "explain": true
  }
}

Usage Examples

Scenario 1: E-commerce Data Analysis

  1. Discover instances and databases
User: "Help me see what database instances are available"
Assistant: Uses the discover_instances tool
  1. Analyze user collection
User: "Analyze the structure of the users table in the e-commerce database"
Assistant: Uses the analyze_collection tool to analyze the users collection
  1. Natural language query
User: "Find active users who registered in the last week, sorted by registration time"
Assistant: Uses generate_query to create a query, then confirm_query to execute it

Scenario 2: Log Data Query

  1. Semantic analysis
User: "Help me understand the meaning of fields in the logs collection"
Assistant: Uses manage_semantics for batch semantic analysis
  1. Complex aggregate query
User: "Count error logs by hour, grouped by time"
Assistant: Generates and executes an aggregate query

Troubleshooting

Common Issues

MongoDB Connection Failure

# Check MongoDB service status
python scripts/check_db.py

# Manually test MongoDB connection
python -c "
from pymongo import MongoClient
client = MongoClient('mongodb://localhost:27017/')
print('MongoDB connection successful')
"

# Check if MongoDB service is running
# Linux/macOS
sudo systemctl status mongod
# Windows
net start | findstr -i mongo

Configuration File Not Found

# Check if configuration file exists
ls -la config.yaml

# Create configuration file from example
cp config.example.yaml config.yaml

# Set environment variable
export QUERYNEST_CONFIG_PATH=/path/to/QueryNest/config.yaml

MCP Service Connection Failure

  • Check MCP client configuration file format
  • Confirm project path is correct (use absolute paths)
  • Verify MongoDB service is running
  • Check if config.yaml file exists

Dependency Package Issues

cd /path/to/QueryNest

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

# Check Python version
python --version

# Check key package installation status
pip list | grep -E "(mcp|pymongo|motor)"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "QueryNest" '{"command":"uvx","args":["--from","/path/to/QueryNest","--no-cache","querynest-mcp"],"cwd":"/path/to/QueryNest","env":{"QUERYNEST_CONFIG_PATH":"/path/to/QueryNest/config.yaml","QUERYNEST_LOG_LEVEL":"INFO"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "QueryNest": {
            "command": "uvx",
            "args": [
                "--from",
                "/path/to/QueryNest",
                "--no-cache",
                "querynest-mcp"
            ],
            "cwd": "/path/to/QueryNest",
            "env": {
                "QUERYNEST_CONFIG_PATH": "/path/to/QueryNest/config.yaml",
                "QUERYNEST_LOG_LEVEL": "INFO"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "QueryNest": {
            "command": "uvx",
            "args": [
                "--from",
                "/path/to/QueryNest",
                "--no-cache",
                "querynest-mcp"
            ],
            "cwd": "/path/to/QueryNest",
            "env": {
                "QUERYNEST_CONFIG_PATH": "/path/to/QueryNest/config.yaml",
                "QUERYNEST_LOG_LEVEL": "INFO"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later