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

01

Read-only by design — there are no write operations, and aggregation rejects $out and $merge rather than trusting the pipeline

02

Schema inference — sample documents to discover a collection's real structure, with configurable sample size and nesting depth

03

Full read surface — find, get by id, count, sample, distinct and aggregate, over databases, collections, indexes and stats

04

Extended JSON everywhere — every JSON argument accepts EJSON, so $date and $oid work in filters, sorts, projections and pipelines

05

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

06

Refuses to silently overwrite — a conflicting credential alias errors with a hint about rotating versus referencing, rather than clobbering the stored value

07

LLM-safe credential entry — credential add --form uses a native OS dialog, so the secret never touches argv or the model's context

08

--echo-query shows exactly what ran — emitted verbatim, with real field order and nulls kept, because there the shape is the data

09

Honest output shaping — empty fields pruned and keys sorted, so a missing key means no value; index specs and query echoes are exempt

10

Truncation you can undo — long strings are cut with a companion length field, and --expand or --full brings them back

11

@meta and @pagination trailers — command context and has_more / total_items / next_cursor, rather than a silent cut-off

12

MCP server — the read-only data commands as MCP tools, over stdio or HTTP with optional local OAuth

13

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

>_ List databases
$ agent-mongo database list
>_ Infer a collection's schema from real documents
$ agent-mongo collection schema myapp users --sample-size 100
>_ Query with a filter
$ agent-mongo query find myapp users --filter '{"age":{"$gte":21}}' --limit 10
>_ Filter on a BSON date using Extended JSON
$ agent-mongo query find myapp events --filter '{"createdAt":{"$gt":{"$date":"2026-01-01T00:00:00Z"}}}'
>_ Fetch one document by ObjectId
$ agent-mongo query get myapp users 665a1b2c3d4e5f6a7b8c9d0e
>_ Distinct values for a field
$ agent-mongo query distinct myapp orders status
>_ Run an aggregation pipeline
$ agent-mongo query aggregate myapp orders --pipeline '[{"$group":{"_id":"$status","count":{"$sum":1}}}]'
>_ See exactly what query ran
$ agent-mongo query count myapp orders --filter '{"status":"pending"}' --echo-query