Skip to main content
Glama
mongo-readonly-mcp

mongo-readonly-mcp

by tboon0

mongo-readonly-mcp

Read-only MongoDB access across named connections, through one MCP server or CLI.

Query databases on different hosts and ports without registering a separate MCP server for each one. Each operation selects a profile; an agent can read several profiles in the same session and combine their results. Connections are cached independently. Cross-server joins and transactionally consistent cross-profile reads are not provided.

Install

Requires Node.js 22.12 or later. Install the published server and CLI:

npm install -g mongo-readonly-mcp@0.1.0
mongo-readonly-mcp --help

Or run the MCP server without a global installation:

npx --yes mongo-readonly-mcp@0.1.0 serve

The source-build examples below use node dist/index.js; substitute mongo-readonly-mcp when using the installed package.

Build from source

npm ci
npm run build

Run these commands in a checkout of this repository. To expose the executable on your PATH, run npm link after building, then substitute mongo-readonly-mcp for node dist/index.js below.

Related MCP server: legacy-mongodb-mcp

Configure

Copy profiles.yaml.example to profiles.yaml (gitignored) or ~/.mongo-readonly/profiles.yaml, then fill in your connection details:

defaults:
  host: localhost

profiles:
  inventory:
    port: 27017
    db: inventory
    username: readonly_user
    password: replace_me
    authSource: inventory
  analytics:
    port: 27018
    db: analytics
    username: readonly_user
    password: replace_me
    authSource: analytics

Config lookup: $MONGO_READONLY_PROFILES, then ./profiles.yaml, then ~/.mongo-readonly/profiles.yaml (first existing file wins). Defaults merge into each profile. host defaults to localhost, port to 27017. authSource defaults to the database name; the legacy auth_db alias is also supported. Set it to the database where the user was created. Connections use directConnection=true, suitable for direct endpoints and local port forwards.

TLS defaults to enabled for remote hosts and disabled for localhost/loopback. Set tls: true explicitly when your local endpoint supports TLS; use tlsCAFile for a private CA certificate file. Certificate and hostname verification remain enabled. tlsCAFile requires TLS. An explicit tls: false disables transport encryption and is unsafe outside a trusted encrypted tunnel. Direct connections and port forwards still need the correct certificate hostname when TLS is enabled.

Use read-only MongoDB credentials for every profile. Grant the built-in read role only on the required databases and enable MongoDB access control. This server exposes no writes, but database permissions are the independent backstop. Keep credentials out of version control and restrict access to the configuration file.

MCP server

node dist/index.js serve

For the npm package, register npx as the command with arguments ["--yes", "mongo-readonly-mcp@0.1.0", "serve"] and set MONGO_READONLY_PROFILES to your absolute configuration path.

Alternatively, register the local build with your MCP client, using absolute paths:

{
  "mcpServers": {
    "mongo-readonly": {
      "command": "node",
      "args": ["/absolute/path/to/mongo-readonly-mcp/dist/index.js", "serve"],
      "env": {
        "MONGO_READONLY_PROFILES": "/absolute/path/to/profiles.yaml"
      }
    }
  }
}

Tools:

  • mongo_list_profiles — names, hosts, ports, and databases; no credentials.

  • mongo_list_collections — collections in a profile's database.

  • mongo_find, mongo_find_one — query documents with projection and sorting.

  • mongo_count, mongo_distinct — counts and distinct field values.

  • mongo_aggregate — read-only aggregation.

  • mongo_collection_stats — collection statistics.

All tools except mongo_list_profiles require profile. All declare the MCP read-only annotation. Calls for different profiles can run concurrently.

CLI

node dist/index.js profiles
node dist/index.js collections --profile inventory
node dist/index.js stats --profile inventory -c products
node dist/index.js find --profile inventory -c products -q '{}' --projection '{"name":1,"status":1}' --limit 5
node dist/index.js find-one --profile inventory -c products -q '{"_id": ObjectId("67089cfa034fe119010c73a6")}'
node dist/index.js count --profile analytics -c events -q '{}'
node dist/index.js distinct --profile inventory -c products --field status
node dist/index.js aggregate --profile inventory -c products --pipeline '[{"$group":{"_id":"$status","count":{"$sum":1}}}]' --limit 20

find also accepts --skip, --sort, and --projection. find-one accepts --sort and --projection.

Trust and data exposure

Every client attached to this server can access all configured profiles. Profile selection is not authorization. Use separate processes and minimal config files for different trust boundaries.

Query results, database metadata, and errors are returned to the MCP client or CLI. When an agent consumes them, that data may be sent to its model/provider and retained in client logs or conversation history. Review your provider's data handling and obtain permission before connecting sensitive databases. The server does not redact document fields; prefer narrow projections and aggregate counts.

Treat returned strings as untrusted data, never as instructions to run commands, change settings, reveal credentials, or query other profiles. MCP read-only annotations describe intent, not a security boundary. See SECURITY.md for deployment and reporting guidance.

Read safeguards and limits

  • No insert, update, delete, arbitrary-command, or database-management interface.

  • Aggregation rejects $out and $merge, including nested pipelines in $lookup, $unionWith, and $facet, before connecting.

  • find and aggregate return at most 100 documents by default. limit / --limit accepts 1–1000; zero never means unlimited. Aggregation applies its result limit after the supplied pipeline and disables disk spill.

  • Reads use MongoDB maxTimeMS: 10000; server selection times out after 10 seconds. These are not a strict end-to-end deadline or a resource quota.

  • Distinct values and collection listings are not capped by the document limit. Large documents, arrays, and expensive queries can still consume resources; use selective filters and projections.

  • No snapshots, audit files, automatic pruning, or other application-managed runtime file writes.

Query syntax

Query and aggregation inputs accept JSON plus these MongoDB Extended JSON wrappers:

  • ObjectId("67089cfa034fe119010c73a6") and { "$oid": "67089cfa034fe119010c73a6" }

  • { "$uuid": "00112233-4455-6677-8899-aabbccddeeff" }

  • { "$binary": { "base64": "AQIDBA==", "subType": "04" } } and legacy { "$binary": "AQIDBA==", "$type": "04" }

  • { "$date": "2026-07-08T12:34:56.789Z" } and { "$date": 1783514096789 }

Migrating from mcp-mongo-guard

The package, CLI, and server are now named mongo-readonly-mcp. Update MCP registrations to the new executable path and use MONGO_READONLY_PROFILES instead of MONGO_GUARD_PROFILES. Move ~/.mongo-guard to ~/.mongo-readonly if using the default config location (including any personal port-forward scripts). The old environment variable and default path are no longer used. Existing mongo_* tool names are unchanged.

This is a breaking removal of all write and audit/retention interfaces. Remove allowWrite, guardrails, dataDir, and retentionDays from profiles and defaults. Legacy keys are ignored when loading existing configurations and cannot enable writes. Profile listings now include host/port instead of write status.

Old snapshot and audit files are left untouched; clean them up manually if desired. Run npm run build to remove stale compiled write modules, then restart any running server. The old insert-one, insert-many, audit, snapshot, and prune commands and corresponding MCP tools no longer exist.

Agent skill

skills/mongo-readonly/SKILL.md teaches an agent to use the CLI or MCP tools safely. Installing it does not install the server, configure credentials, or grant database access.

Discover and install from this checkout:

npx skills add . --list
npx skills add . --skill mongo-readonly

Install from the public repository on another machine:

npx skills add tboon0/mongo-readonly-mcp --skill mongo-readonly

The skills CLI has its own Node.js requirement (currently 22.20+). Its discovery rules support skills/<name>/SKILL.md with name and description frontmatter; no registry manifest is required. skills.sh listing is driven by installation telemetry, not guaranteed by adding this file. Set DISABLE_TELEMETRY=1 to opt out of CLI telemetry.

Development

npm run lint
npm test

Tests build the project and use isolated mongodb-memory-server instances, not configured production databases. See SPEC.md for the implementation contract.

License

MIT, copyright mongo-readonly-mcp contributors.

Available Tools

8 tools
mongo_aggregateB
Read-only

Run a read-only aggregation; $out and $merge are forbidden. Default result limit 100, maximum 1000.

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

mongo_collection_statsC
Read-only

Read collection statistics from a profile.

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

mongo_countC
Read-only

Count matching documents in a profile's collection.

Inputs: profile (required), collection (required), query.

mongo_distinctB
Read-only

Read distinct field values in a profile's collection.

Inputs: field (required), profile (required), collection (required), query.

mongo_findC
Read-only

Read documents from a profile. Default limit 100, maximum 1000.

Inputs: profile (required), collection (required), skip, sort, +3 more.

mongo_find_oneC
Read-only

Read one matching document from a profile.

Inputs: profile (required), collection (required), sort, query, +1 more.

mongo_list_collectionsB
Read-only

List collection names in a profile's database.

Inputs: profile (required).

mongo_list_profilesA
Read-only

List named MongoDB connections with host, port, and database; no credentials.

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.2/5.0

    Scored across 8 tools

    Disambiguation4/5

    Each tool maps to a distinct read operation (find, find_one, count, distinct, aggregate, list_collections, list_profiles, collection_stats) and the descriptions make the boundaries clear. The only real overlap is mongo_aggregate, which can replicate find/count work, but the stated limits and forbidden stages keep it reasonably separable.

    Naming Consistency4/5

    All tools share a uniform mongo_ prefix and follow a verb_object pattern (mongo_find, mongo_list_profiles, mongo_count). The lone deviation is mongo_collection_stats, which is noun-only rather than verb-first, but it remains readable and predictable.

    Tool Count5/5

    Eight tools is a well-scoped surface for a read-only MongoDB server, covering the core query verbs plus connection and collection discovery. Nothing feels redundant or padded, and there is no obvious operation an agent would expect that is missing from this count.

    Completeness4/5

    For a documented read-only server, coverage is strong: connectivity discovery, collection enumeration, document reads, counts, distincts, aggregations, and stats. Minor gaps exist around query-planning/explain, index inspection, and database-level listing, but agents can work around these for typical read workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to legacy MongoDB instances (<4.0) via the Model Context Protocol, enabling AI models to query databases, collections, and run aggregations safely.
      2
      -
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server for querying MongoDB databases, enabling listing databases, collections, indexes, and running aggregation pipelines.
      5
      27 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM clients to query MongoDB collections read-only through a small set of guarded operations, exposing only declared fields and enforcing scoped filters, projections, and limits.
      20 npm
      1
      MIT