MongoDB MCP VN

English | Tiếng Việt

mongodb-mcp-vn is a Python MCP server for bounded MongoDB discovery, read, and explicitly guarded mutation operations. It returns MongoDB Extended JSON and never returns a configured connection URI or driver exception details.

Install and run

Install the released package:

uv tool install mongodb-mcp-vn

Or, from a source checkout:

cd uvx/mongodb
uv sync --extra dev

Set a least-privilege URI outside source control. This local example contains no credentials:

export MONGO_URI='mongodb://localhost:27017'

stdio (default)

Use stdio for a local MCP client such as Codex or Claude Desktop:

MCP_TRANSPORT=stdio mongodb-mcp-vn

The equivalent source command is uv run mongodb-mcp-vn.

MCP client JSON configuration (stdio)

Add this to your Codex or Claude Desktop MCP configuration. Do not set MCP_TRANSPORT; stdio is the default.

{
  "mcpServers": {
    "mongodb-mcp-vn": {
      "command": "uvx",
      "args": ["mongodb-mcp-vn"],
      "env": {
        "MONGO_URI": "mongodb://localhost:27017",
        "MONGO_ALLOW_WRITE": "false"
      }
    }
  }
}

Set MONGO_ALLOW_WRITE to true only when the MCP client must create, update, delete documents, or drop a collection; restart the client after changing it.

Tool inputs are direct JSON fields: call mongodb_ping with {}, and call mongodb_list_databases with {"limit": 50}. Do not wrap them in params.

Streamable HTTP

Use streamable HTTP only behind an appropriate network boundary. The defaults are 127.0.0.1:8005; streamable_http is accepted as an alias.

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8005 mongodb-mcp-vn

MCP_PORT must be an integer from 1 through 65535. Unsupported transports fail at startup rather than silently changing transport.

Tools

All collection and database names preserve the supplied bytes; blank-only names are rejected. Read tools have a bounded limit (maximum 100) and return Extended JSON.

Tool	Operation
mongodb_ping	Check connectivity and report MongoDB server version.
mongodb_list_databases	Page through accessible database metadata.
mongodb_list_collections	Page through collections in one database.
mongodb_describe_collection	Return collection options, count, sampled fields, and indexes.
mongodb_list_indexes	Page through index specifications.
mongodb_find_documents	Bounded find with Extended JSON filter, projection, and sort.
mongodb_aggregate	Bounded read aggregation; $out and $merge are forbidden.
mongodb_create_collection	Create one collection after the write gate passes.
mongodb_create_index	Create one index after the write gate passes.
mongodb_insert_documents	Insert a non-empty Extended JSON document array after the write gate passes.
mongodb_update_documents	Run explicit update_one or update_many after the write gate passes.
mongodb_delete_documents	Run explicit delete_one or delete_many after the write gate passes.
mongodb_drop_collection	Drop exactly one collection after the write gate and exact confirmation pass.

Security and writes

• MONGO_URI is required; keep it in your shell, secret manager, or MCP-client environment—not in this README, source, or logs.
• Writes are disabled by default. Set MONGO_ALLOW_WRITE=true before starting the server only when a mutation is intended; restart to return to the safe default.
• mongodb_drop_collection additionally requires confirmation to be byte-for-byte identical to collection_name, including whitespace and case.
• Use a MongoDB role limited to the required databases and actions. This server does not provide generic commands, database drops, user/role administration, or shutdown.
• Extended JSON inputs are shape-checked before client acquisition; invalid requests and driver failures are redacted instead of echoing secrets.

Compatibility

The server supports MongoDB deployments from 3.6 onward for the discovery/read features used here; use a current supported MongoDB release for production security updates. MongoDB 5.0+ x86_64 server binaries require AVX. On a non-AVX host, run a compatible pre-5.0 MongoDB deployment where it is still appropriate for your risk profile, move the database to supported hardware, or use a compatible managed service; this MCP server cannot bypass the database binary's CPU requirement. See MongoDB's production notes.

Fixed local evaluation fixture

The ten independent, read-only questions in evaluations/mongodb_read_only.xml use a fixed local database named mongodb_mcp_evaluation. Each requires multi-tool, cross-collection exploration (metadata/index inspection plus bounded reads or aggregations), rather than a single lookup. Seed it only in a disposable local MongoDB instance before an evaluation; it is not created by the MCP server.

Collection	Fixed documents
customers	{customer_id: "c-001", name: "Ada", tier: "bronze"}, {customer_id: "c-002", name: "Binh", tier: "gold"}, {customer_id: "c-003", name: "Chi", tier: "gold"}
products	{sku: "T-100", name: "Tea", category: "beverage", price: 12}, {sku: "C-200", name: "Coffee", category: "beverage", price: 20}, {sku: "N-300", name: "Notebook", category: "stationery", price: 8}
orders	{order_id: "o-1001", customer_id: "c-001", sku: "T-100", quantity: 2, amount: 24, status: "paid", created_at: "2024-01-10"}, {order_id: "o-1002", customer_id: "c-002", sku: "C-200", quantity: 1, amount: 20, status: "paid", created_at: "2024-01-11"}, {order_id: "o-1003", customer_id: "c-001", sku: "N-300", quantity: 3, amount: 24, status: "pending", created_at: "2024-02-01"}, {order_id: "o-1004", customer_id: "c-003", sku: "T-100", quantity: 5, amount: 60, status: "paid", created_at: "2024-02-02"}, {order_id: "o-1005", customer_id: "c-002", sku: "N-300", quantity: 1, amount: 8, status: "cancelled", created_at: "2024-02-03"}

Create only these fixed indexes for the fixture: the default _id_ indexes plus orders.order_id as unique index order_id_1, orders.(customer_id, created_at) as customer_id_1_created_at_-1, and orders.status as status_1.

Release

Build and publish only from a clean, reviewed checkout. publish.sh and publish.bat accept no token argument, contain no credential, and use only the environment variable UV_PUBLISH_TOKEN:

export UV_PUBLISH_TOKEN='set-this-in-your-secret-manager-or-shell'
./publish.sh

Do not commit, print, or replace the token.

Tiếng Việt

mongodb-mcp-vn là MCP server Python cho các thao tác khám phá/đọc MongoDB có giới hạn và các thao tác ghi được bảo vệ rõ ràng. Server trả về MongoDB Extended JSON và không trả lại URI đã cấu hình hoặc chi tiết lỗi từ driver.

Cài đặt và transport

uv tool install mongodb-mcp-vn
export MONGO_URI='mongodb://localhost:27017'
MCP_TRANSPORT=stdio mongodb-mcp-vn

stdio là mặc định cho MCP client cục bộ. Với Streamable HTTP, dùng biên mạng phù hợp:

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8005 mongodb-mcp-vn

MCP_PORT phải nằm trong 1–65535.

Cấu hình JSON cho MCP client (stdio)

Thêm block JSON sau vào cấu hình MCP của Codex hoặc Claude Desktop. Không cần khai báo MCP_TRANSPORT vì stdio là mặc định:

{
  "mcpServers": {
    "mongodb-mcp-vn": {
      "command": "uvx",
      "args": ["mongodb-mcp-vn"],
      "env": {
        "MONGO_URI": "mongodb://localhost:27017",
        "MONGO_ALLOW_WRITE": "false"
      }
    }
  }
}

Chỉ đổi MONGO_ALLOW_WRITE thành true khi cần tạo/sửa/xóa dữ liệu; restart MCP client sau khi đổi biến môi trường.

Công cụ

Công cụ	Mục đích
mongodb_ping	Kiểm tra kết nối và phiên bản MongoDB.
mongodb_list_databases / mongodb_list_collections	Liệt kê có phân trang database hoặc collection được phép truy cập.
mongodb_describe_collection / mongodb_list_indexes	Xem metadata, mẫu schema, số lượng và index có giới hạn.
mongodb_find_documents / mongodb_aggregate	Đọc có giới hạn; aggregate chặn $out và $merge.
mongodb_create_collection / mongodb_create_index / mongodb_insert_documents	Tạo collection/index hoặc chèn document sau write gate.
mongodb_update_documents / mongodb_delete_documents	Chỉ chạy rõ ràng update_one/update_many hoặc delete_one/delete_many.
mongodb_drop_collection	Xóa một collection khi write gate và xác nhận chính xác đều hợp lệ.

Bảo mật và ghi dữ liệu

• MONGO_URI là bắt buộc; đặt trong secret manager hoặc biến môi trường, không lưu vào mã nguồn, tài liệu, hay log.
• Ghi bị tắt mặc định. Chỉ đặt MONGO_ALLOW_WRITE=true trước khi khởi động khi thật sự cần ghi; khởi động lại không có biến này để trở về chế độ an toàn.
• Khi xóa collection, confirmation phải khớp chính xác từng ký tự với collection_name, bao gồm hoa/thường và khoảng trắng.
• Dùng MongoDB role tối thiểu cần thiết. Không có lệnh tổng quát, xóa database, quản lý user/role, hoặc shutdown.

Tương thích và phát hành

Server hỗ trợ MongoDB 3.6+ cho các khả năng khám phá/đọc nêu trên. MongoDB 5.0+ trên x86_64 yêu cầu AVX; máy không có AVX cần dùng deployment trước 5.0 phù hợp với chính sách vận hành, chuyển sang phần cứng được hỗ trợ, hoặc dịch vụ managed tương thích. MCP server không thể vượt qua giới hạn CPU của binary MongoDB.

publish.sh và publish.bat chỉ đọc UV_PUBLISH_TOKEN từ môi trường; không truyền, ghi, hay thay đổi token trong script. Bộ fixture cố định và 10 câu hỏi chỉ-đọc nằm ở evaluations/mongodb_read_only.xml.