MO
Database

MongoDB Lens MCP Server for Databases

Optimize MongoDB deployments with MongoDB Lens, a full-featured MCP server for managing, monitoring and querying databases efficiently.

View on GitHub

Overview

MongoDB Lens is an MCP (Model Context Protocol) server designed to manage, monitor, and query MongoDB deployments. It exposes a set of purpose-built tools that let developer tooling, automation agents, and LLM-powered assistants interact with a live MongoDB instance in a structured, auditable way. By implementing a tool-based API, MongoDB Lens makes it easy to run read-only diagnostics, inspect schema and indexes, and execute safe queries from external systems.

This server is useful when you need to integrate database operations into automated workflows or AI assistants while retaining clear boundaries and logged tool usage. Instead of giving an agent full database credentials and unrestricted shell access, MongoDB Lens provides a controlled surface of operations (list databases, run aggregated queries, collect metrics, explain slow queries) that return structured JSON suitable for downstream processing.

Features

  • Tool-oriented MCP server exposing database operations as callable actions
  • Read-only and controlled query execution to reduce risk
  • Introspection tools: list databases, collections, indexes, and sample documents
  • Query tools: find, aggregate, explain, and explainPlan extraction
  • Operational metrics: collection stats, serverStatus snapshots, index usage
  • JSON-structured responses suitable for automated agents and LLMs
  • Configurable connection settings and access controls
  • Docker-friendly and environment-driven configuration

Installation / Configuration

Below are common ways to run MongoDB Lens. Adjust commands for your environment.

Clone repository

git clone https://github.com/furey/mongodb-lens.git
cd mongodb-lens

Run with Docker (recommended for quick start)

docker pull furey/mongodb-lens:latest
docker run -p 8080:8080 \
  -e MONGO_URI="mongodb://user:[email protected]:27017/?authSource=admin" \
  -e LENS_PORT=8080 \
  --name mongodb-lens \
  furey/mongodb-lens:latest

Environment variables

MONGO_URI      - MongoDB connection string (required)
LENS_PORT      - HTTP port for the MCP server (default: 8080)
LENS_READ_ONLY - If true, restricts endpoints to read-only operations (default: true)
LENS_API_KEY   - Optional API key for simple auth to the MCP endpoint

Example YAML configuration (if the server supports a config file)

mongo:
  uri: "mongodb://user:[email protected]:27017/?authSource=admin"
server:
  port: 8080
  readOnly: true
auth:
  apiKey: "replace-with-your-key"

Systemd unit (example)

[Unit]
Description=MongoDB Lens MCP Server
After=network.target

[Service]
Environment=MONGO_URI=mongodb://user:pass@localhost:27017/?authSource=admin
Environment=LENS_PORT=8080
ExecStart=/usr/local/bin/mongodb-lens
Restart=on-failure

[Install]
WantedBy=multi-user.target

Available Tools / Resources

MongoDB Lens exposes a set of tools intended to be invoked via the MCP tool interface. Typical tool names and returned JSON shapes include:

  • list_databases — returns an array of database names and basic stats
  • list_collections — given a database, returns collections and counts
  • sample_documents — returns example documents from a collection
  • find — runs a restricted find query and returns result documents
  • aggregate — runs pipeline aggregations with execution safeguards
  • explain_query — returns an explain plan for a provided query
  • collection_stats — returns output similar to db.collection.stats()
  • server_status — snapshot of serverStatus metrics

Resources:

  • Repository: https://github.com/furey/mongodb-lens
  • API: Look for an /mcp or /tools endpoint for MCP-compatible tool invocation (POST JSON)

Example tool invocation (conceptual)

curl -X POST "http://localhost:8080/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LENS_API_KEY" \
  -d '{"tool":"list_databases","input":{}}'

Use Cases

  1. LLM-assisted query generation and validation

    • Scenario: An assistant constructs a MongoDB query for a user. Rather than running arbitrary code, the assistant calls MongoDB Lens’s explain_query or sample_documents tools to validate the query shape and preview results. This avoids exposing raw driver access to the assistant.
    • Example: Use explain_query to get the execution plan before running an aggregate.

  2. Diagnostics and performance troubleshooting

    • Scenario: An operations engineer wants to triage slow queries. Lens provides explain plans and server_status snapshots that can be consumed by automated scripts or sent to incident channels for review.
    • Example: Trigger server_status and explain_query for the slow query fingerprint and attach results to a ticket.

  3. Automated discovery and migration planning

    • Scenario: During a migration, you need to collect schema heatmaps, collection stats, and index usage. Lens can export collection_stats and index information for each database, producing structured JSON for ingest into migration tools.
    • Example: Iterate over list_databases -> list_collections -> collection_stats and output a compatibility report.

  4. Read-only data exploration in multi-tenant environments

    • Scenario: Provide support engineers or analytics workflows with a constrained interface to preview documents and metadata without granting full DB credentials.
    • Example: support agents call sample_documents and list_collections to see examples and counts, controlled via LENS_READ_ONLY and API keys.

Tips for Developers

  • Run Lens behind an authenticated gateway if exposing beyond a trusted network.
  • Enable read-only mode for environments where write access is not necessary.
  • Log MCP invocations to maintain audit trails for automated agents and LLMs.
  • Use explain tools before running heavy aggregations to avoid expensive operations.

For full implementation details and API specifics, consult the repository README and source at https://github.com/furey/mongodb-lens.

Tags:database