agent-mongo

Read-only MongoDB CLI for AI agents

TypeScript v0.3.0 MIT

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.

1. 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.

2. 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.

3. 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