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
• Aggregation Pipeline Stages
• Indexing Strategies
• Explain Plan