mongodb

name	mongodb
description	MongoDB database client with Docker-based mongosh CLI
runtime	docker

MongoDB Skill

Query and manage MongoDB databases through a containerized mongosh client.

Overview

This skill provides AI agents with MongoDB database access through a Docker-based mongosh (MongoDB Shell) client. Run queries, manage collections, perform aggregations, and analyze data.

When to Use This Skill

• Execute MongoDB queries and aggregations
• Manage collections and indexes
• Insert, update, and delete documents
• Analyze data with aggregation pipelines
• Perform database administration tasks

Prerequisites

• Docker installed and running
• Network access to target MongoDB server
• MongoDB user credentials with appropriate permissions

Configuration

Add to your .skill-engine.toml:

[skills.mongodb]
source = "docker:mongo:7"
runtime = "docker"
description = "MongoDB database client"

[skills.mongodb.docker]
image = "mongo:7"
entrypoint = "mongosh"
network = "bridge"
memory = "256m"
rm = true

Configuration Explained

Setting	Value	Description
image	mongo:7	Official MongoDB 7 image with mongosh
entrypoint	mongosh	Use the MongoDB Shell client
network	bridge	Bridge network to connect to external databases
memory	256m	Memory limit for the container
rm	true	Auto-remove container after execution

Usage

Arguments after -- are passed directly to mongosh:

skill run mongodb -- [mongosh options] [connection string] [script]

Common Operations

Connect and Run Query

# Connect to local MongoDB
skill run mongodb -- --eval "db.users.find().limit(5)" mongodb://localhost:27017/mydb

# Connect with authentication
skill run mongodb -- --eval "db.users.find()" "mongodb://user:password@localhost:27017/mydb"

# Connect to replica set
skill run mongodb -- --eval "db.users.countDocuments()" "mongodb://host1,host2,host3/mydb?replicaSet=rs0"

List Databases and Collections

# List all databases
skill run mongodb -- --eval "db.adminCommand('listDatabases')" mongodb://localhost:27017

# List collections in a database
skill run mongodb -- --eval "db.getCollectionNames()" mongodb://localhost:27017/mydb

# Get collection stats
skill run mongodb -- --eval "db.users.stats()" mongodb://localhost:27017/mydb

Query Documents

# Find all documents
skill run mongodb -- --eval "db.users.find().toArray()" mongodb://localhost:27017/mydb

# Find with filter
skill run mongodb -- --eval "db.users.find({status: 'active'}).toArray()" mongodb://localhost:27017/mydb

# Find with projection
skill run mongodb -- --eval "db.users.find({}, {name: 1, email: 1}).toArray()" mongodb://localhost:27017/mydb

# Find one document
skill run mongodb -- --eval "db.users.findOne({email: '[e-mail]'})" mongodb://localhost:27017/mydb

# Count documents
skill run mongodb -- --eval "db.users.countDocuments({status: 'active'})" mongodb://localhost:27017/mydb

Insert Documents

# Insert one document
skill run mongodb -- --eval "db.users.insertOne({name: 'Alice', email: '[e-mail]', status: 'active'})" mongodb://localhost:27017/mydb

# Insert many documents
skill run mongodb -- --eval "db.logs.insertMany([{event: 'login', user: 'alice'}, {event: 'logout', user: 'bob'}])" mongodb://localhost:27017/mydb

Update Documents

# Update one document
skill run mongodb -- --eval "db.users.updateOne({email: '[e-mail]'}, {\$set: {status: 'inactive'}})" mongodb://localhost:27017/mydb

# Update many documents
skill run mongodb -- --eval "db.users.updateMany({lastLogin: {\$lt: new Date('2024-01-01')}}, {\$set: {status: 'dormant'}})" mongodb://localhost:27017/mydb

# Upsert
skill run mongodb -- --eval "db.settings.updateOne({key: 'theme'}, {\$set: {value: 'dark'}}, {upsert: true})" mongodb://localhost:27017/mydb

Delete Documents

# Delete one document
skill run mongodb -- --eval "db.sessions.deleteOne({_id: ObjectId('...')})" mongodb://localhost:27017/mydb

# Delete many documents
skill run mongodb -- --eval "db.logs.deleteMany({createdAt: {\$lt: new Date('2024-01-01')}})" mongodb://localhost:27017/mydb

Aggregation Pipelines

# Group and count
skill run mongodb -- --eval "db.orders.aggregate([{\$match: {status: 'completed'}}, {\$group: {_id: '\$customer', total: {\$sum: '\$amount'}, count: {\$sum: 1}}}, {\$sort: {total: -1}}, {\$limit: 10}]).toArray()" mongodb://localhost:27017/mydb

# Date-based aggregation
skill run mongodb -- --eval "db.events.aggregate([{\$match: {type: 'purchase'}}, {\$group: {_id: {\$dateToString: {format: '%Y-%m-%d', date: '\$timestamp'}}, count: {\$sum: 1}, revenue: {\$sum: '\$amount'}}}, {\$sort: {_id: -1}}]).toArray()" mongodb://localhost:27017/mydb

Index Management

# List indexes
skill run mongodb -- --eval "db.users.getIndexes()" mongodb://localhost:27017/mydb

# Create index
skill run mongodb -- --eval "db.users.createIndex({email: 1}, {unique: true})" mongodb://localhost:27017/mydb

# Create compound index
skill run mongodb -- --eval "db.orders.createIndex({customer: 1, createdAt: -1})" mongodb://localhost:27017/mydb

# Drop index
skill run mongodb -- --eval "db.users.dropIndex('email_1')" mongodb://localhost:27017/mydb

Advanced Examples

Connect to MongoDB Atlas

# Atlas connection
skill run mongodb -- --eval "db.users.find().limit(5).toArray()" "mongodb+srv://user:[e-mail]/mydb"

Execute JavaScript File

# Run a script file (mount volume first)
skill run mongodb -- mongodb://localhost:27017/mydb /scripts/migration.js

Output as JSON

# Use EJSON for strict JSON output
skill run mongodb -- --eval "EJSON.stringify(db.users.find().limit(5).toArray())" mongodb://localhost:27017/mydb

Troubleshooting

Connection Refused

MongoNetworkError: connect ECONNREFUSED

Solutions:

• Verify MongoDB server is running
• Check host and port are correct
• Ensure container can reach the database (network mode)

Authentication Failed

MongoServerError: Authentication failed

Solutions:

• Verify username and password
• Check authentication database (usually admin)
• Ensure user has permissions for the database

Command Not Found

SyntaxError: Unexpected token

Solution: Escape special characters in shell. Use single quotes for --eval.

Common Errors

Error	Cause	Solution
ECONNREFUSED	Can't connect	Check host/port/firewall
Authentication failed	Bad credentials	Verify user/password
not authorized	Missing permissions	Check user roles
ns not found	Collection missing	Verify collection name

Docker Image Details

Property	Value
Image	mongo:7
Size	~700MB (compressed ~250MB)
Platforms	linux/amd64, linux/arm64
Includes	mongosh, mongodump, mongorestore, mongoexport

Security Considerations

• Use connection strings with credentials (avoid plain text in scripts)
• Connect over TLS/SSL when possible
• Use read-only users for query operations
• Container runs with limited memory
• Network is bridge mode (isolated from host network)

Resources

• MongoDB Documentation
• mongosh Reference
• Docker MongoDB Image