MQLens
Documentation

Getting started with MQLens

MQLens is a native desktop GUI for MongoDB. Point it at any deployment — local, self-hosted, or Atlas — and browse, query, aggregate, and manage your data from a single cross-platform app: a multi-window workspace, built-in data generation, an MCP server for AI agents, and read-only safeguards for production.

Install

Download the build for your platform from the download section or the latest release:

  • macOS — open the .dmg and drag MQLens to Applications. Check the release notes for signing and notarization details.

Windows

Download the .exe or .msi installer from thelatest release page. Requires Windows 10 or later (x64).

Setup (.exe, recommended)

  1. Double-click MQLens_*_x64-setup.exe.
  2. Approve the UAC prompt if Windows asks for permission.
  3. Follow the setup wizard, then launch MQLens from the Start menu.

Setup (.msi)

Double-click MQLens_*.msi and follow the prompts, or install from an elevated Command Prompt or PowerShell:

msiexec /i MQLens_*.msi

Troubleshooting: if SmartScreen shows "Windows protected your PC", check that the installer came from the official release page andverify your download before continuing.

Linux

Grab the .deb or .AppImage from thelatest release page.

Debian / Ubuntu (.deb)

sudo apt install ./MQLens_*.deb
# or:
sudo dpkg -i MQLens_*.deb

Any distro (.AppImage)

chmod +x MQLens_*.AppImage
./MQLens_*.AppImage

Troubleshooting: if the AppImage says "Permission denied" or refuses to start, the execute bit was probably lost during download — runchmod +x on the file again. Some browsers save AppImages without the executable flag until you set it manually.

To use the embedded shell you'll also need mongosh on your PATH.

Your first connection

Supported servers: MongoDB 4.2 or newer, including Atlas. That's the floor of the official MongoDB Rust driver MQLens is built on. Older servers aren't supported yet — a pre-3.6 server predates the wire protocol the driver speaks, so it closes the connection during the handshake rather than reporting its version.

  1. Launch MQLens and set a master password — this encrypts your saved connection profiles at rest.
  2. Create a connection: enter a host (standalone or replica set) or paste a full connection string.
  3. Configure transport and auth as needed — TLS (system CA, custom CA file, or client certificate), an SSH tunnel, or a SOCKS5 proxy, plus your auth mechanism.
  4. Hit Test Connection. The staged check reports each real phase: parse → DNS resolve → connect → ping.
  5. Connect, then browse databases, collections, views, and GridFS buckets in the tree and start querying.
MQLens document table showing sample customer records
Browse sample customer records in the document workspace.

Multi-window workspace

Every open collection, shell, or view is a tab. You can split the tab area into panes and pull tabs out into separate OS windows, so a query, a shell, and cluster health can sit side by side across monitors.

  • Multiple tabs per collection — open a collection more than once to run different queries against it side by side. Right-click a collection → Open in New Tab, or double-click a collection that's already open, to add another tab (each starts on the default query). To branch from a query you're already looking at, right-click its tab → Duplicate Tab — the new tab opens with the same find filter / sort / projection or aggregation pipeline, ready to tweak. When many tabs are open, the tab strip scrolls horizontally.
  • Split panes — drag a tab onto the edge of a pane to split in that direction (left / right / top / bottom), or use the command palette (Ctrl/Cmd K) → Split Right / Split Down. Drag a tab onto another pane's center to move it there; drag the divider to resize.
  • Detach to a new window — right-click a tab and choose Detach to New Window, or Move to Window → to send it to an already-open window. Each window is a full workspace with its own sidebar.
  • Session restore — quit and relaunch and your windows, splits, and tabs come back exactly as you left them. Restored tabs wake disconnected; a banner offers a one-click Reconnect per connection (credentials come from your unlocked vault — nothing auto-connects to production on its own).

Data generation

Seed a collection with realistic synthetic documents for testing or demos.

  1. Right-click a collection → Generate Data… to start from a template inferred from that collection's schema ("generate more like this"), or right-click a database → Generate Data… to start from a blank template and name a target collection (it's created if it doesn't exist).
  2. Shape the documents in the visual builder — pick a generator per field (name, email, number, date, boolean, ObjectId, UUID, lorem, pick-from-list), and add nested objects or arrays with count ranges. Toggle to raw JSON for full control; the two stay in sync.
  3. The preview pane shows a few generated documents live. Set a document count (up to 50,000) and click Generate.
  4. Confirm the count when prompted. Large runs execute as a background task you can watch and cancel from the Tasks panel; an open view of that collection refreshes when it finishes.

MCP server (AI agents)

MQLens can act as a Model Context Protocolserver, letting Claude Code, Cursor, or any MCP client drive MongoDB through your existing connections as tools. It is off by default.

  1. In the Connection Manager, edit a connection and tick Expose to MCP agents. Only opted-in connections are ever visible to an agent.
  2. Open Settings → MCP and switch the server on (the app's vault must be unlocked). A bearer token is generated for you.
  3. Click Copy next to the Claude Code or Cursor snippet and paste it into that client's MCP configuration. The agent connects over loopback HTTP.
  4. The agent can now list databases and collections, run find and aggregations, read explain plans, analyze schema, and list indexes. Writes (insert / update / delete / create index) require an explicit confirmation argument, and any connection you've marked read-only rejects writes outright.

Agent-initiated connections appear in the sidebar with a via MCP badge, and a live call log is shown in Settings → MCP. See the full MCP tool reference.

Production safeguards

Mark a connection as protected so writes are blocked or gated — enforced in the backend, for the UI and AI agents alike, not just by hiding buttons.

  • Read-only — every write is rejected (insert, update, delete, drop, rename, index changes, imports, generation, mongosh). A red banner appears on the connection's tabs and a badge on its sidebar row; write actions are disabled in the grid.
  • Confirm-destructive — ordinary writes work, but destructive operations (drop, delete-many, update-many, rename) require you to type the collection name to confirm. An amber banner marks the connection.
  • Normal — full read/write (the default).

Set the mode in the Connection Manager when editing a connection. The mode is applied when you connect, so if you change it on a live connection, reconnect for it to take effect.

Settings

  • Language — Settings → Language switches the interface between English, German, and Simplified Chinese; untranslated text falls back to English.

Verifying downloads

To verify a release download, get its matching detached GPG signature (.asc) from the release page and run the commands below with your downloaded filenames. Check the release notes for platform-specific signing details.

# Import the MQLens release public key (once):
gpg --import KEYS    # from the repo, or:
curl -L https://mqlens.com/KEYS | gpg --import

# Verify an asset against its .asc:
gpg --verify MQLens_0.1.0_amd64.deb.asc MQLens_0.1.0_amd64.deb

Signing key — MQLens Releases <[email protected]>, fingerprint:

8E10 C09D 1FEC 8C8F 90B1  DB7E 5804 6649 06E7 D373

Security model

  • Connection credentials and settings are encrypted at rest behind your master password using AES-256-GCM with Argon2id key derivation. Nothing is stored in plaintext once the vault is initialized.
  • Disabling TLS certificate validation is an explicit, opt-in choice (with an in-app warning) — it is never silent.
  • AI provider API keys are held in the backend, out of the frontend bundle.
MQLens talks directly to whatever MongoDB deployment you point it at. Use the usual care with production credentials.

Build from source

git clone https://github.com/mqlens/mqlens-mongodb.git
cd mqlens-mongodb
npm install
npm run tauri dev      # run the desktop app with hot reload
npm run tauri build    # produce a platform installer / bundle

Prerequisites

Hit a snag? Open an issue on GitHub →