agent-mongo
Read-only MongoDB CLI for AI agents
- Language
- Go
- Version
- 0.12.1
- License
- PolyForm Perimeter 1.0.0
- Category
- CLI Tool
A read-only MongoDB CLI for AI agents that need safe database exploration. Schema inference from real documents, find, get, count, sample, distinct and aggregation, plus database and collection statistics — with read-only enforced by design rather than by convention, and passwords lifted out of connection strings into the OS keychain.
Preview
Features
Read-only by design — there are no write operations, and aggregation rejects $out and $merge rather than trusting the pipeline
Schema inference — sample documents to discover a collection's real structure, with configurable sample size and nesting depth
Full read surface — find, get by id, count, sample, distinct and aggregate, over databases, collections, indexes and stats
Extended JSON everywhere — every JSON argument accepts EJSON, so $date and $oid work in filters, sorts, projections and pipelines
Passwords never sit in config — a user:pass embedded in a URI is moved into a keychain credential named for the connection, and connection list redacts even connections saved before that existed
Refuses to silently overwrite — a conflicting credential alias errors with a hint about rotating versus referencing, rather than clobbering the stored value
LLM-safe credential entry — credential add --form uses a native OS dialog, so the secret never touches argv or the model's context
--echo-query shows exactly what ran — emitted verbatim, with real field order and nulls kept, because there the shape is the data
Honest output shaping — empty fields pruned and keys sorted, so a missing key means no value; index specs and query echoes are exempt
Truncation you can undo — long strings are cut with a companion length field, and --expand or --full brings them back
@meta and @pagination trailers — command context and has_more / total_items / next_cursor, rather than a silent cut-off
MCP server — the read-only data commands as MCP tools, over stdio or HTTP with optional local OAuth
Zero runtime dependencies — a single static Go binary
Install
Homebrew
$ brew install shhac/tap/agent-mongo AI Agent Skill
$ npx skills add shhac/agent-skills --skill agent-mongo --global GitHub Release (macOS)
$ curl -L https://github.com/shhac/agent-mongo/releases/latest/download/agent-mongo-darwin-arm64.tar.gz | tar xz Go Install
$ go install github.com/shhac/agent-mongo/cmd/agent-mongo@latest Build from Source (needs Go 1.26+)
$ git clone https://github.com/shhac/agent-mongo.git && cd agent-mongo && make build Getting Started
agent-mongo needs a MongoDB connection. Store the password as a credential rather than in the connection string — it then lives in the OS keychain, can be rotated in one place, and can be shared across staging, prod and the rest.
01 · Store the password without it passing through chat
$ agent-mongo credential add acme --username deploy --form --form opens a native OS dialog, so the secret never touches argv or the model's context. --password works for non-interactive setups. Either way it is redacted in list output.
02 · Add a connection that references it
$ agent-mongo connection add staging "mongodb+srv://cluster.mongodb.net/myapp" --credential acme The credential is injected at connect time. If you do embed user:pass in the URI, agent-mongo moves it into a keychain credential for you rather than leaving it in config.json.
03 · Test the connection
$ agent-mongo connection test Pings the default, or name one explicitly. connection set-default picks which is used when -c is absent.
04 · Discover the shape before querying it
$ agent-mongo collection schema myapp users --sample-size 100 Every command group has a usage page — agent-mongo query usage — and agent-mongo usage gives the overview.
Usage
$ agent-mongo database list $ agent-mongo collection schema myapp users --sample-size 100 $ agent-mongo query find myapp users --filter '{"age":{"$gte":21}}' --limit 10 $ agent-mongo query find myapp events --filter '{"createdAt":{"$gt":{"$date":"2026-01-01T00:00:00Z"}}}' $ agent-mongo query get myapp users 665a1b2c3d4e5f6a7b8c9d0e $ agent-mongo query distinct myapp orders status $ agent-mongo query aggregate myapp orders --pipeline '[{"$group":{"_id":"$status","count":{"$sum":1}}}]' $ agent-mongo query count myapp orders --filter '{"status":"pending"}' --echo-query