mongo-readonly-mcp
Read-only MongoDB querying across multiple named connection profiles via MCP tools.
List configured profiles with host, port, and database, without exposing credentials.
List collection names in a profile's database.
Query documents with
mongo_findandmongo_find_one, including filters, projections, sorting, skip, and limits.Count matching documents with
mongo_count.Read distinct field values with
mongo_distinct.Run read-only aggregations with
mongo_aggregate;$outand$mergeare forbidden.Read collection statistics with
mongo_collection_stats.No write, arbitrary command, or database-management operations are exposed.
Provides read-only access to MongoDB databases across named connection profiles, enabling listing profiles and collections, querying documents with projections and sorting, counting documents, retrieving distinct values, running read-only aggregations, and inspecting collection statistics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mongo-readonly-mcp list collections in the inventory profile"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 --helpOr run the MCP server without a global installation:
npx --yes mongo-readonly-mcp@0.1.0 serveThe 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 buildRun 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: analyticsConfig 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 serveFor 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 20find 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
$outand$merge, including nested pipelines in$lookup,$unionWith, and$facet, before connecting.findandaggregatereturn at most 100 documents by default.limit/--limitaccepts 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-readonlyInstall from the public repository on another machine:
npx skills add tboon0/mongo-readonly-mcp --skill mongo-readonlyThe 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 testTests 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 toolsmongo_aggregateBRead-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_statsCRead-only
Read collection statistics from a profile.
Inputs: profile (required), collection (required).
mongo_countCRead-only
Count matching documents in a profile's collection.
Inputs: profile (required), collection (required), query.
mongo_distinctBRead-only
Read distinct field values in a profile's collection.
Inputs: field (required), profile (required), collection (required), query.
mongo_findCRead-only
Read documents from a profile. Default limit 100, maximum 1000.
Inputs: profile (required), collection (required), skip, sort, +3 more.
mongo_find_oneCRead-only
Read one matching document from a profile.
Inputs: profile (required), collection (required), sort, query, +1 more.
mongo_list_collectionsBRead-only
List collection names in a profile's database.
Inputs: profile (required).
mongo_list_profilesARead-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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Read-only cited financial datasets, bounded research queries and source diagnostics.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceProvides read-only access to MongoDB databases for LLMs to inspect collection schemas and execute aggregation pipelines.9 npm27-
- FlicenseNot gradedqualityDmaintenanceProvides 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-
- AlicenseAqualityDmaintenanceA read-only MCP server for querying MongoDB databases, enabling listing databases, collections, indexes, and running aggregation pipelines.527 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm1MIT