FlowMongo

A Flow Launcher plugin for browsing MongoDB connections, databases, collections, and documents -- without leaving your keyboard.

Default action keyword: mg (rename it in Flow's plugin settings; the plugin reads the real keyword automatically).

---

Installation (Direct)

1. Copy the plugin folder to %APPDATA%\FlowLauncher\Plugins\FlowMongo\
2. Restart Flow Launcher (or mg reload)
3. Run mg add local mongodb://localhost:27017 to add your first connection

No setup needed -- pymongo is bundled in lib/.

---

Connection management

Add a connection

mg add <name> <uri>
mg add local mongodb://localhost:27017
mg add prod mongodb+srv://user:pass@cluster.mongodb.net

Names must be single words (no spaces). URIs must start with mongodb:// or mongodb+srv://.

Remove a connection

mg remove <name>
mg remove prod

Partial name match is supported. Removing a connection also clears its pin, tag, recents, and saved queries.

Test a connection

mg test <name>
mg test local

Pings the server and shows latency inline. Partial name match tests all matches.

List connections

mg
mg <filter>

Type after mg to filter by name. Pinned connections sort to the top.

---

Visual markers

Pin a connection

Right-click any connection -> "Pin to top" / "Unpin from top". Pinned connections show a pin marker and always appear above unpinned ones.

Color / emoji tag

Right-click any connection -> pick a color from the palette (red/green/yellow/blue). Or from the command line:

mg tag <name> <emoji>    # set any emoji or short text
mg tag prod              # clear the tag

Tags show as a prefix in the connection title, e.g. prod with a red tag shows as [red] prod.

---

Navigation

Selection on any result triggers a breadcrumb query -- you never type these manually:

mg :db <conn>              -- list databases
mg :col <conn> <db>        -- list collections
mg :doc <conn> <db> <col>  -- list documents

Each level has a "<- back" row at the top. Press Escape or select it to go up a level.

Collections view

Shows each collection with:

• estimated document count
• collection type badge: view, timeseries, or plain collection
• system collections (system.*) are hidden

Right-click a database row -> "Open in Compass here" to launch MongoDB Compass at that database.

---

Document browsing

mg :doc <conn> <db> <col>
mg :doc <conn> <db> <col> <filter>

Each document row shows:

• Title: the _id value
• Subtitle: up to 8 field previews (key: value * key: value)

Selecting a document (Enter) copies its full Extended JSON to the clipboard.

Filter types

Three filter modes, tried in this order:

1. Direct _id lookup -- type a raw id in the filter slot:

507f1f77bcf86cd799439011          -- 24-hex ObjectId
"some-string-id"                   -- quoted string _id
42                                 -- integer _id

Returns exactly one document via find_one. Fast.

2. Server-side MongoDB query -- start filter with {:

{status: "active"}
{"age": {"$gte": 18}}
{"tags": {"$in": ["a", "b"]}}

Sent directly to MongoDB as a find() filter. Standard MongoDB query syntax (JSON).

3. Client-side text match -- anything else:

john
2024

Filters the already-fetched document list by matching _id or field previews. No server round-trip.

Sort

A "Sort" toggle row appears at the bottom of every document view:

• Natural order (default) -- MongoDB insertion order
• Newest first -- sorts by _id descending; works best with ObjectId _ids where the id encodes creation time

Click the toggle to switch. Sort state survives pagination and filter changes.

Pagination

When a page is full (at the configured document limit), "-> next page" and "<- page back" rows appear at the bottom. Click to advance or go back. Page and sort state are encoded in the query string and survive filter edits.

Document limit

Default: 50 documents per page. Change it in Flow Settings -> Plugins -> FlowMongo -> "Document fetch limit" (range: 1-1000).

---

Document actions

Enter on a document: copy full Extended JSON to clipboard.

Right-click a document for:

• Copy Document JSON -- full Extended JSON (same as Enter)
• Copy _id -- just the raw _id value
• Copy mongosh snippet -- paste-ready db.getSiblingDB("db").col.findOne({_id: ...}) for mongosh
• Back to collection -- return to the current :doc view

---

Connection actions (right-click a connection)

• Pin to top / Unpin from top
• Color tag palette -- 4 preset colors; clicking the active color clears it
• Copy Connection String -- two-step guard; warns the URI contains credentials before copying
• Copy connection name
• Copy host
• Open in MongoDB Compass -- launches Compass with the connection URI
• Test Connection -- pings and logs result
• Remove -- permanently deletes the connection

---

Saved queries

Save a named filter + namespace for quick re-use.

Save a query

While browsing a filtered :doc view, a "Save as query..." row appears at the bottom (only when a filter is active). Click it to pre-fill the save command:

mg q save <name> <conn> <db> <col> <filter>

Edit the name slot and press Enter to save.

Or type it directly:

mg q save active-users myconn mydb users {status:"active"}

List and run saved queries

mg q               -- list all saved queries
mg q <filter>      -- filter by name

Select a query to jump directly to its :doc view with the filter applied.

Right-click a query row -> "Remove query".

Remove a query

mg q remove <name>

---

Recent namespaces

mg recent
mg recent <filter>

Lists the last 10 connection / db / collection namespaces you opened, most-recent first. Select one to jump back. Dead links (connections that were removed) are filtered out automatically.

---

Open in Compass

• Connection level: right-click a connection -> "Open in MongoDB Compass"
• Database level: right-click a database -> "Open in Compass here" (opens Compass with that database pre-selected)

Compass is found at its default install paths. Falls back to the mongodb:// URI scheme if not found.

---

Settings

Configured in Flow Settings -> Plugins -> FlowMongo:

Setting	Default	Description
Document fetch limit	50	Max documents loaded per page (1-1000)

The action keyword (mg by default) can be changed in Flow's plugin settings. The plugin reads the real keyword from Flow's Settings.json automatically -- all breadcrumb navigation updates to match.

---

Known limitations

• Connection names, database names, and collection names with spaces break breadcrumb navigation (args are space-split). Use underscores or hyphens.
• settings.json stores connection URIs in plaintext, including passwords. The file is gitignored but not otherwise protected.
• The plugin runs as a new process per request (Flow's classic Python runtime). The in-memory TTL cache is wiped between keystrokes; there is no cross-request connection pooling.
• The clipboard helper uses PowerShell. If PowerShell is unavailable, copy actions fail silently (logged to stderr).
• Saved queries with {…} filters use standard JSON parsing -- MongoDB extended operators ($oid, $date, etc.) and BSON-specific types are not supported in the filter slot. Use string/number/boolean values only.