/db-mongo

name: db-mongo
description: "Query MongoDB databases configured in .env (DB_MONGO_N_*). Use when the user asks to query, explore, or audit data in a MongoDB database. Picks connection by label (e.g. 'orders-dev', 'analytics-prod') or numeric index. Read-only by default — writes refused unless DB_MONGO_N_ALLOW_WRITE=true on that block."
metadata:
  openclaw:
    requires:
      env:
        - DB_MONGO_1_LABEL
      bins:
        - python3
    primaryEnv: DB_MONGO_1_LABEL
    files:
      - "scripts/*"
      - "references/*"

db-mongo

Query MongoDB databases declared in `.env`. Same numbered block pattern as every other `db-*` and `SOCIAL_*_N_*` integration.

Setup — one-time, per database

Add a block to `.env` (gitignored). Two ways to define a connection:

Option A — URI (recommended for Atlas / managed)

DB_MONGO_1_LABEL=orders-dev
DB_MONGO_1_URI=mongodb+srv://user:pw@cluster0.abc.mongodb.net/orders?retryWrites=true
# DB_MONGO_1_DATABASE=orders          # optional if in URI
# DB_MONGO_1_ALLOW_WRITE=false
# DB_MONGO_1_QUERY_TIMEOUT=30
# DB_MONGO_1_MAX_ROWS=1000

Option B — components

DB_MONGO_2_LABEL=analytics-prod
DB_MONGO_2_HOST=mongo.prod.internal
DB_MONGO_2_PORT=27017
DB_MONGO_2_DATABASE=analytics
DB_MONGO_2_USER=agent_readonly
DB_MONGO_2_PASSWORD=...
# DB_MONGO_2_AUTH_SOURCE=admin        # optional
# DB_MONGO_2_TLS=true                 # optional

URI wins when both are set. `LABEL` is always required.

Usage

All commands output a single JSON line on stdout (safe to pipe).

List configured connections

python3 .claude/skills/db-mongo/scripts/db_client.py accounts

Health-check a connection (MongoDB ping)

python3 .claude/skills/db-mongo/scripts/db_client.py test orders-dev

Find documents

# All (up to MAX_ROWS)
python3 .claude/skills/db-mongo/scripts/db_client.py find orders-dev customers

# With filter (JSON)
python3 .claude/skills/db-mongo/scripts/db_client.py find orders-dev customers \
  '{"status": "active"}' 20

Aggregation pipeline

python3 .claude/skills/db-mongo/scripts/db_client.py aggregate orders-dev orders \
  '[{"$match": {"status": "paid"}}, {"$group": {"_id": "$product", "total": {"$sum": "$amount"}}}]'

Explore database

# List collections
python3 .claude/skills/db-mongo/scripts/db_client.py collections orders-dev

# DB stats (size, object count, index size)
python3 .claude/skills/db-mongo/scripts/db_client.py stats orders-dev

Output shape

Successful find/aggregate:

{
  "ok": true,
  "query_id": "uuid-v4",
  "label": "orders-dev",
  "collection": "customers",
  "documents": [{"_id": "...", "email": "a@b.com"}],
  "row_count": 1,
  "truncated": false,
  "execution_time_ms": 12
}

Guardrails

• **Read-only by default.** Aggregation pipelines containing `$out` or `$merge` (write stages) are refused unless `ALLOW_WRITE=true`. `find` is always safe; no separate write commands are exposed in v1.
• **Query timeout** applied at the server selection, socket, and connect levels.
• **Result size** capped at `MAX_ROWS` (default 1000). For aggregations we stop iterating the cursor at that point.
• **Credentials** never leave `.env`; `accounts` strips password before returning.

Error codes

• `no_connections`, `not_found`, `ambiguous`, `config_error` — same as other `db-*` skills
• `driver_missing` — `pymongo` not installed
• `connection_failed` — network, auth, TLS, or timeout
• `invalid_filter` / `invalid_pipeline` — JSON parse failed
• `write_blocked` — aggregation with `$out`/`$merge` on `ALLOW_WRITE=false`
• `usage` — wrong CLI args

Workflow

1. `accounts` to confirm the connection label. 2. `collections` to see what's in there. 3. `find` or `aggregate` with the smallest query that answers the question. 4. If a pipeline is expensive, ask the user whether to `$limit` earlier or add indexes before running.

Dependencies

• Python 3.10+
• `pymongo` — not pre-installed; `uv pip install pymongo` on first use.

Deep-dive references

Mongo isn't covered by PlanetScale's `database-skills` upstream. When you need authoritative reference, go to the Mongo docs directly:

• [MongoDB Query Operators](https://www.mongodb.com/docs/manual/reference/operator/query/)
• [Aggregation Pipeline Stages](https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/)
• [Indexing Strategies](https://www.mongodb.com/docs/manual/applications/indexes/)
• [Explain Plan](https://www.mongodb.com/docs/manual/reference/method/cursor.explain/)