Skip to content
Back to search

mcp-mongo-server

A Model Context Protocol Server for MongoDB

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/kiliczsh/mcp-mongo-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/kiliczsh/mcp-mongo-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kiliczsh--mcp-mongo-server/badge.svg)](/listings/kiliczsh--mcp-mongo-server)

HTML

<a href="/listings/kiliczsh--mcp-mongo-server"><img src="/api/listings/kiliczsh--mcp-mongo-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Point the server at your database — no install step needed:

npx -y mcp-mongo-server mongodb://localhost:27017/mydatabase

Explore safely, without any chance of changing data:

npx -y mcp-mongo-server mongodb://localhost:27017/mydatabase --read-only

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 167 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP MongoDB Server
  2. ---
  3. ![NPM Version](https://img.shields.io/npm/v/mcp-mongo-server)
  4. ![NPM Downloads](https://img.shields.io/npm/dm/mcp-mongo-server)
  5. ![NPM License](https://img.shields.io/npm/l/mcp-mongo-server)
  6. A Model Context Protocol (MCP) server that lets AI assistants work with your MongoDB databases. It exposes your collections, infers their schemas, and runs queries, aggregations, and writes through a standard interface — so tools like Claude Desktop and Cursor can read and reason about your data.
  7. ## Demo
  8. [![MCP MongoDB Server Demo | Claude Desktop](https://img.youtube.com/vi/FI-oE_voCpA/0.jpg)](https://www.youtube.com/watch?v=FI-oE_voCpA)
  9. ## Why use it
  10. - **Talk to your database in plain language** — the assistant discovers your collections and their shape automatically.
  11. - **Read-only mode** — restrict write operations globally or per connection.
  12. - **Works everywhere** — connects to standalone, replica set, sharded, and Atlas deployments, over plain or TLS connections.
  13. ## Key Features
  14. - **Read-Only Mode** — blocks every write path (insert, update, index creation, and aggregation stages like `$out`/`$merge` that could modify data).
  15. - **Smart ObjectId Handling** — configurable `auto`/`none`/`force` conversion of 24-character hex strings to ObjectIds.
  16. - **Schema Inference** — automatic collection schema detection from document samples.
  17. - **Query & Aggregation** — full query and aggregation pipeline support, with optional `explain` plans.
  18. - **Write Operations** — insert, update, and index creation (when read-only mode is off).
  19. - **Time Conversion** — a `convertTime` helper turns Unix timestamps and date strings into UTC/GMT/ISO, so date queries stay unambiguous across timezones.
  20. - **Progress & Cancellation** — long operations report progress and can be cancelled mid-flight.
  21. - **Two Transports** — run locally over stdio, or expose an HTTP endpoint for remote access.
  22. ## Requirements
  23. - Node.js 20 or newer
  24. ## Quick Start
  25. Point the server at your database — no install step needed:
  26. ```bash
  27. npx -y mcp-mongo-server mongodb://localhost:27017/mydatabase
  28. ```
  29. Explore safely, without any chance of changing data:
  30. ```bash
  31. npx -y mcp-mongo-server mongodb://localhost:27017/mydatabase --read-only
  32. ```
  33. ## Usage
  34. ### Local (stdio)
  35. This is the default, used by Claude Desktop, Cursor, and other local clients:
  36. ```bash
  37. npx -y mcp-mongo-server "mongodb://user:pass@localhost:27017/mydatabase"
  38. ```
  39. ### Remote (HTTP)
  40. Expose an HTTP endpoint at `/mcp` for remote or multi-client access:
  41. ```bash
  42. npx -y mcp-mongo-server "mongodb://user:pass@localhost:27017/mydatabase" --transport http --port 3001
  43. ```
  44. By default, only requests without a browser `Origin` (CLIs, IDEs) and requests
  45. from `localhost` are accepted; everything else is rejected with `403` to guard
  46. against DNS-rebinding attacks. Allow specific browser origins with
  47. `--allowed-origins`:
  48. ```bash
  49. npx -y mcp-mongo-server "mongodb://..." --transport http --port 3001 --allowed-origins "https://app.example.com"
  50. ```
  51. ### Options
  52. | Flag | Description |
  53. |------|-------------|
  54. | `--read-only`, `-r` | Block all write operations |
  55. | `--allow-cross-db` | Allow aggregation `$out`/`$merge`/`$lookup` to target other databases (off by default) |
  56. | `--allow-server-js` | Allow server-side JavaScript operators `$function`/`$where`/`$accumulator` (off by default) |
  57. | `--transport`, `-t` | `stdio` (default) or `http` |
  58. | `--port`, `-p` | HTTP port (default `3001`) |
  59. | `--allowed-origins` | Comma-separated browser origins to allow in HTTP mode |
  60. | `--json-limit` | Max HTTP request body size (default `10mb`) |
  61. | `--auth-token` | Require `Authorization: Bearer <token>` on the HTTP endpoint |
  62. ### Environment Variables
  63. | Variable | Description |
  64. |----------|-------------|
  65. | `MCP_MONGODB_URI` | MongoDB connection URI (alternative to the argument) |
  66. | `MCP_MONGODB_CONNECTIONS` | JSON object of named MongoDB connections and their database permissions |
  67. | `MCP_MONGODB_MAX_RESULT_DOCUMENTS` | Optional document cap for `query` and `aggregate` |
  68. | `MCP_MONGODB_MAX_RESULT_BYTES` | Optional UTF-8 byte cap for the compact JSON results array, minimum 2 |
  69. | `MCP_MONGODB_QUERY_TIMEOUT_MS` | Optional MongoDB operation timeout in milliseconds for `query`, `aggregate`, `listIndexes`, and query count and explain operations |
  70. | `MCP_MONGODB_READONLY` | Enable read-only mode (`"true"`) |
  71. | `MCP_MONGODB_ALLOW_CROSS_DB` | Allow cross-database aggregation stages (`"true"`) |
  72. | `MCP_MONGODB_ALLOW_SERVER_JS` | Allow server-side JavaScript operators (`"true"`) |
  73. | `MCP_PORT` | HTTP port |
  74. | `MCP_HTTP_ALLOWED_ORIGINS` | Comma-separated browser origins to allow in HTTP mode |
  75. | `MCP_HTTP_JSON_LIMIT` | Max HTTP request body size (default `10mb`) |
  76. | `MCP_HTTP_AUTH_TOKEN` | Bearer token required to access the HTTP endpoint |
  77. ### Named connections
  78. Set `MCP_MONGODB_CONNECTIONS` to a JSON string. This MCP client configuration
  79. uses a local build and the two [Docker test databases](docs/development.md#local-mongodb-test-environment).
  80. ```json
  81. {
  82. "mcpServers": {
  83. "mongodb": {
  84. "command": "node",
  85. "args": [
  86. "/absolute/path/to/mcp-mongo-server/build/index.js"
  87. ],
  88. "env": {
  89. "MCP_MONGODB_CONNECTIONS": "{\"default\":{\"uri\":\"mongodb://127.0.0.1:37017/mcp_test\"},\"analytics\":{\"uri\":\"mongodb://127.0.0.1:37018/mcp_test?directConnection=true\",\"databases\":[\"mcp_test\",\"mcp_test_secondary\"],\"readOnly\":true}}"
  90. }
  91. }
  92. }
  93. }
  94. ```
  95. - Discover targets with `listConnections` and `listDatabases`. Pass `connectionId` and `database` to database tools and the collection analysis prompt. Omitted selectors use the `default` connection and its URI database.
  96. - Omit `databases` to allow only the URI database. If supplied, the list must include the URI database. Global read-only mode applies to every connection.
  97. - Write tools appear in tool discovery when at least one connection is writable. Use `listConnections` to choose a writable target.
  98. - A positional URI or `MCP_MONGODB_URI` can supply `default` when the JSON contains only secondary connections. Named connections default to a 5-second server selection timeout. Set `serverSelectionTimeoutMS` in the URI to override it.
  99. - If a connection is offline, `resources/list` reports its ID and fails. Tools targeting other connections remain usable.
  100. ## Security
  101. **Database scope.** The server operates on the selected database.
  102. Named connections restrict selection to their configured databases.
  103. Aggregation stages that reach another database (`$out`, `$merge`,
  104. `$lookup` with an explicit `db`) are rejected by default, so a pipeline can't
  105. quietly read from or write to databases you didn't point it at. Enable them
  106. with `--allow-cross-db` if you need them. Named connections still enforce their
  107. database allowlist.
  108. **Server-side JavaScript.** The operators `$function`, `$where`, and
  109. `$accumulator` are blocked by default in aggregation pipelines and in the
  110. filters for `query`, `count`, and `update`. In read-write mode,
  111. `--allow-server-js` enables these operators.
  112. **Read-only mode** blocks writes, including the `$out` and `$merge`
  113. aggregation stages. It also blocks server-side JavaScript even when
  114. `--allow-server-js` is set.
  115. **Least privilege.** Application-level checks only go so far — the strongest
  116. guarantee comes from the database. Connect with a MongoDB user scoped to just
  117. the database you need, with read-only permissions when the assistant only needs
  118. to explore. That way the database itself enforces the boundary, as defense in
  119. depth.
  120. ## Documentation
  121. - [Integration Guide](docs/integration.md) — Claude Desktop, Windsurf, Cursor, Docker
  122. - [Available Tools](docs/tools.md) — query, aggregate, update, insert, and more
  123. - [Development](docs/development.md) — setup, scripts, and debugging
  124. - [Contributing](CONTRIBUTING.md)
  125. ## License
  126. MIT — see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.