name: mongo-db description: Interact with a MongoDB database for persistent document storage. Supports full CRUD operations (find, insert, update, delete), aggregation pipelines, collection management, and index creation. Use when any agent needs to store or retrieve data in MongoDB — for example, persisting financial records, budgets, watchlists, or any structured data across sessions. metadata: {"openclaw": {"requires": {"bins": ["python3"]}, "emoji": "🍃"}}

MongoDB — Document Storage Skill

Use this skill whenever an agent needs to read or write persistent data to MongoDB. All operations are performed via a Python CLI script and return JSON output.

When to use

User asks to "save to the database", "store this in Mongo", "retrieve from MongoDB"
An agent needs to persist data across sessions (budgets, transactions, summaries, watchlists)
An agent needs to query, filter, or aggregate stored records
A new collection or schema (validator) needs to be set up

Setup (first run only)

Local MongoDB: If you need to install MongoDB on Ubuntu, see INSTALL-UBUNTU.md. For Atlas, use your connection string in config or env.

Run the setup script once from the workspace root to create a virtual environment and install pymongo:

bash skills/mongo-db/scripts/setup.sh

This creates skills/mongo-db/scripts/.venv/ and installs dependencies there. After setup, invoke the client using the venv interpreter:

skills/mongo-db/scripts/.venv/bin/python3 skills/mongo-db/scripts/mongo_client.py '<json>'

Configuration

Connection is resolved in this order (first match wins):

Option 1 — Environment variable (recommended)

MONGO_URI=mongodb+srv://user:password@cluster.mongodb.net/mydb
MONGO_DB=mydb   # optional if the db is in the URI

Option 2 — config.json (local file, gitignored)

Copy the example and fill in your values:

cp skills/mongo-db/config.example.json skills/mongo-db/config.json

Edit skills/mongo-db/config.json:

{
  "uri": "mongodb://localhost:27017",
  "database": "mydb",
  "username": "optional",
  "password": "optional"
}

Option 3 — Individual env vars

MONGO_HOST=localhost
MONGO_PORT=27017
MONGO_USER=myuser
MONGO_PASSWORD=mypassword
MONGO_DB=mydb

CLI interface

All operations use a single JSON payload argument:

PYTHON=skills/mongo-db/scripts/.venv/bin/python3
$PYTHON skills/mongo-db/scripts/mongo_client.py '<json_payload>'

Payload schema:

{
  "operation": "<op>",
  "database": "<optional override>",
  "collection": "<collection name>",
  ...operation-specific fields
}

Output is always JSON: {"success": true, ...result_fields} or {"success": false, "error": "..."}.

Operations Reference

List databases

{"operation": "list_databases"}

List collections in a database

{"operation": "list_collections", "database": "mydb"}

Create a collection (with optional JSON Schema validator)

{
  "operation": "create_collection",
  "database": "mydb",
  "collection": "budgets",
  "validator": {
    "$jsonSchema": {
      "bsonType": "object",
      "required": ["period", "income"],
      "properties": {
        "period": {"bsonType": "string"},
        "income": {"bsonType": "number"}
      }
    }
  }
}

Drop a collection

Always confirm with the user before dropping. Requires "confirm": true.

{"operation": "drop_collection", "database": "mydb", "collection": "old_data", "confirm": true}

Create an index

{
  "operation": "create_index",
  "database": "mydb",
  "collection": "transactions",
  "keys": {"date": 1, "category": 1},
  "unique": false
}

Find documents

{
  "operation": "find",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"category": "groceries"},
  "projection": {"_id": 0, "date": 1, "amount": 1, "description": 1},
  "sort": {"date": -1},
  "limit": 20
}

Find one document

{
  "operation": "find_one",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"id": "txn_20260131_0001"}
}

Count documents

{
  "operation": "count",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"type": "expense"}
}

Insert one document

{
  "operation": "insert_one",
  "database": "mydb",
  "collection": "transactions",
  "document": {
    "id": "txn_20260201_0001",
    "date": "2026-02-01",
    "description": "Supermarket",
    "amount": -85.50,
    "category": "groceries",
    "type": "expense"
  }
}

Insert many documents

{
  "operation": "insert_many",
  "database": "mydb",
  "collection": "transactions",
  "documents": [
    {"date": "2026-02-01", "description": "Coffee", "amount": -4.50, "category": "dining"},
    {"date": "2026-02-02", "description": "Salary", "amount": 5000, "category": "income"}
  ]
}

Update one document

{
  "operation": "update_one",
  "database": "mydb",
  "collection": "budget",
  "filter": {"period": "monthly"},
  "update": {"$set": {"income": 5500, "last_updated": "2026-02-01"}},
  "upsert": false
}

Update many documents

{
  "operation": "update_many",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"category": "food"},
  "update": {"$set": {"category": "groceries"}}
}

Replace one document

{
  "operation": "replace_one",
  "database": "mydb",
  "collection": "budget",
  "filter": {"period": "monthly"},
  "replacement": {"period": "monthly", "income": 5500, "currency": "USD"},
  "upsert": true
}

Delete one document

Always confirm with the user before deleting. Requires "confirm": true.

{
  "operation": "delete_one",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"id": "txn_20260131_0001"},
  "confirm": true
}

Delete many documents

Always confirm with the user before deleting. Requires "confirm": true.

{
  "operation": "delete_many",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"source_file": "january_statement.pdf"},
  "confirm": true
}

Aggregate

{
  "operation": "aggregate",
  "database": "mydb",
  "collection": "transactions",
  "pipeline": [
    {"$match": {"type": "expense"}},
    {"$group": {"_id": "$category", "total": {"$sum": "$amount"}, "count": {"$sum": 1}}},
    {"$sort": {"total": 1}}
  ]
}

Notes

Destructive operations (delete_one, delete_many, drop_collection) require "confirm": true in the payload. Always ask the user to confirm before including this flag.
ObjectId fields are serialized as strings in all output.
Database override: the "database" field in the payload overrides the default database from config/env for that single call.
Schema validation: use create_collection with a "validator" to enforce document structure at the MongoDB level. This is the recommended approach for agents that write structured data (e.g. the finance-budget agent's budget and transaction collections).
Upsert pattern: for config-like documents (one per type), use replace_one with "upsert": true to create-or-replace atomically.
If pymongo is missing, re-run bash skills/mongo-db/scripts/setup.sh.

Mongo Db Client Tool

Description