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/"

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

accounts to confirm the connection label.
collections to see what's in there.
find or aggregate with the smallest query that answers the question.
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: