agent-mongo

Read-only MongoDB CLI for AI agents

Language: TypeScript
Version: 0.6.0
License: MIT
Category: CLI Tool

A read-only MongoDB CLI designed for AI agents that need safe database exploration. It provides schema inference, flexible querying, and aggregation pipelines — with built-in safety rails that prevent any write operations.

Preview

Features

Structured JSON output — all output to stdout, errors to stderr

LLM-optimized docs via agent-mongo usage for agent consumption

Read-only by design — no write operations, aggregation rejects $out/$merge

Schema inference — sample documents to discover collection structure

Flexible querying — find, count, sample, distinct, aggregate

Connection management with named profiles and credential reuse

Configurable safety limits — max documents, query timeout

Zero runtime dependencies — single compiled binary

Install

Homebrew

$ brew install shhac/tap/agent-mongo

AI Agent Skill

$ npx skills add shhac/agent-mongo

GitHub Release (macOS)

$ curl -L https://github.com/shhac/agent-mongo/releases/latest/download/agent-mongo-darwin-arm64.tar.gz | tar xz

Build from Source

$ git clone https://github.com/shhac/agent-mongo.git && cd agent-mongo && bun install && bun run build

Getting Started

agent-mongo needs a MongoDB connection before it can query anything. We recommend storing credentials separately from connection strings so passwords can be rotated in one place.

01 · Store your credentials

$ agent-mongo credential add acme --username deploy --password secret123

Passwords are stored in macOS Keychain when available. Credentials are always redacted in list output.

02 · Add a connection using the credential

$ agent-mongo connection add staging "mongodb+srv://cluster.mongodb.net/myapp" --credential acme

The credential is injected at connect time, keeping passwords out of connection strings and invisible to LLMs. One credential can be shared across staging, prod, etc.

03 · Test the connection

$ agent-mongo connection test

Usage

>_ List databases

$ agent-mongo database list

>_ Infer collection schema

$ agent-mongo collection schema users --sample-size 100

>_ Query documents

$ agent-mongo query find users --filter '{"active": true}' --limit 10

>_ Run an aggregation pipeline

$ agent-mongo query aggregate orders --pipeline '[{"$group": {"_id": "$status", "count": {"$sum": 1}}}]'

>_ Get collection stats

$ agent-mongo collection stats users