Use DBGorilla from the command line
You can use DBGorilla from a terminal with mcporter, a small open-source command-line tool for MCP servers. It suits shell scripts, scheduled jobs and CI, quick checks without opening an AI tool, and AI tools that cannot add an MCP connector. Nothing is installed inside your databases, and no AI assistant is required.
It uses DBGorilla’s read-only set of tools at https://app.dbgorilla.com/mcp/readonly. That set
leaves out the tools that create, change, or delete things in DBGorilla. A few tools in it still run
work against a database on your behalf, such as an EXPLAIN plan, so treat it as a set of reading tools.
It does not guarantee that nothing can change.
The output below is trimmed example output from a demo workspace. Your names and IDs will differ.
To connect an AI tool instead, see Connect an MCP client by hand.
Turn it on
Section titled “Turn it on”Install
Section titled “Install”You need Node.js 20 or newer.
npm install -g mcportermcporter --version0.9.0Add DBGorilla
Section titled “Add DBGorilla”mcporter keeps its settings in config/mcporter.json under the folder you run it from. Create one
folder and always run mcporter from there.
mkdir ~/dbgorilla-cli && cd ~/dbgorilla-climcporter config add dbgorilla --url https://app.dbgorilla.com/mcp/readonlyAdded 'dbgorilla' to /home/you/dbgorilla-cli/config/mcporter.jsonThen choose one of two ways to sign in. Each person uses their own DBGorilla account.
Option A: sign in through the browser (OAuth)
Section titled “Option A: sign in through the browser (OAuth)”mcporter auth dbgorillaA browser opens on the DBGorilla sign-in page. It says “mcporter (dbgorilla) is requesting access to DBGorilla on your behalf.” Sign in the way you normally do: with your organization, username and password, or with Google or GitHub. The browser then shows “Authorization successful. You can return to the CLI.” and the terminal prints:
[mcporter] Authorization complete. 40 tools available.If no browser opens, for example over SSH, the terminal prints a line starting If the browser did not open, visit https://app.dbgorilla.com/mcp/authorize?.... Open that link on the same machine. It
sends you back to a local address (127.0.0.1), so it must be the machine running mcporter.
Option B: an MCP API key
Section titled “Option B: an MCP API key”Use this for a server or script where a browser is not practical.
To get your key in DBGorilla:
- Click your name in the sidebar to open the user menu.
- Choose Profile.
- Open the MCP Access tab.
- Under Bearer token, use Copy to clipboard. Regenerate API Key replaces the key and Delete API Key removes it.
Treat the key like a password. It acts as you.
Keep the key out of the file by putting it in an environment variable. mcporter fills in ${DBGORILLA_API_KEY}
when it runs:
export DBGORILLA_API_KEY='paste-your-key-here'mcporter config add dbgorilla --url https://app.dbgorilla.com/mcp/readonly \ --header 'Authorization=Bearer ${DBGORILLA_API_KEY}'The single quotes matter. They keep the key itself out of config/mcporter.json.
Check it works
Section titled “Check it works”List the tools:
mcporter list dbgorilladbgorilla function discover_components(): object; function get_topology_overview(component_id: string): object; function list_topology_snapshots(component_id: string, limit?: number): object; ...Add --schema to see every parameter for every tool.
Plain mcporter list, without the server name, reports an HTTP 405 SSE error for DBGorilla,
even though every call works. The DBGorilla server answers a plain GET request with 405, which
the MCP specification allows, and mcporter reports that as an error. Use mcporter list dbgorilla.
List your databases
Section titled “List your databases”mcporter call dbgorilla.discover_components{ "result": [ { "component_id": "9bc21246-e089-5391-ad14-5d21d77197d8", "name": "Storefront", "component_type": "postgres", "version": "16.15 (Debian 16.15-1.pgdg13+2)", "hosting": "Self-hosted" } ]}Copy the component_id. Every other call needs it. The examples set it once:
C=9bc21246-e089-5391-ad14-5d21d77197d8list_databases is a different tool: it lists databases DBGorilla hosts for you. For your own
databases, use discover_components.
Read open recommendations
Section titled “Read open recommendations”mcporter call dbgorilla.list_recommendations component_id=$C status_filter=open limit=3#5 priority=medium risk=low category=query_improvement status=open title=Move inventory pacing delays outside the complete transaction#4 priority=critical risk=medium category=security status=open title=Separate API runtime credentials from storefront_app superuser and migration credentials#3 priority=critical risk=low category=security status=open title=Fix confirmed SQL injection in storefront.fn_find_products before performance work
Not all results shown, next page available by calling list_recommendations with the same inputs along with next_cursor=...If a result prints as escaped JSON instead of text, add --output text to the command.
Filters: priority_filter (low, medium, high, critical), risk_filter, category_filter,
status_filter (open, complete, ignored, closed).
Read one in full:
mcporter call dbgorilla.view_recommendation component_id=$C number=5#5 priority=medium risk=low category=query_improvement status=open version=1 created_at=2026-11-07T09:15:33Z
# Move inventory pacing delays outside the complete transaction
## Recommended changeIn the external inventory-writing SQL/script workflow for database `storefront`, remove the deliberatedatabase sleep from the transaction responsible for the observed blocking session `13567`. If pacing isrequired, perform it only **after the entire inventory/order transaction has committed** ...Check one query’s performance
Section titled “Check one query’s performance”First, list the top queries over a time window. Times are UTC. dimension can be total_duration,
avg_duration, invocations, rows, shared_blks_read and more
(mcporter call dbgorilla.discover_workloads component_id=$C lists them all).
mcporter call dbgorilla.get_top_workload component_id=$C dimension=total_duration \ start=2026-11-07T00:00:00Z end=2026-11-07T15:57:45Z limit=3Top workload ranked by total_duration (3): | # | total_duration (ms) | invocations | avg_duration (ms) | user | fingerprint | |---|---|---|---|---|---| | 1 | 1705691 | 17295 | 98.6234 | storefront_app | 44fc11468e033234 | | 2 | 396130 | 10133 | 39.0931 | storefront_app | 9024d46808bd1a0d | | 3 | 227169 | 33840 | 6.71303 | storefront_app | a93b7f3312b4c328 |If you get No workload items found, the window has no data. Move it closer to now.
Then view one query’s details using its fingerprint:
mcporter call dbgorilla.investigate_workload component_id=$C fingerprint=44fc11468e033234 \ start=2026-11-07T00:00:00Z end=2026-11-07T15:57:45ZWorkload fingerprint=44fc11468e033234: description: SELECT date_trunc($2, placed_at)::date AS month, count(*), COALESCE(sum(total_cents), $3) FROM storefront.orders WHERE EXTRACT($4 FROM placed_at) = $1 GROUP BY 1 ORDER BY sum(total_cents) DESC invocations=17295 avg_duration=98.6234 ms total_duration=1705691 ms rows=121065 total shared_blks_hit=15886192 total shared_blks_read=0 total trend (14 buckets of 3600s ...): | bucket | invocations | avg_duration (ms) | total_duration (ms) | ... | 2026-11-07T02:00:00Z | 203 | 98.0274 | 19899.6 | ... | 2026-11-07T03:00:00Z | 1347 | 104.361 | 140575 | ... ...Sign out
Section titled “Sign out”mcporter config logout dbgorillaCleared cached credentials for 'dbgorilla'This clears the saved sign-in for Option A. Do not use mcporter auth dbgorilla --reset to sign
out: it clears the sign-in and then immediately opens a new one. For Option B, delete the key in
Profile > MCP Access > Delete API Key, and run unset DBGORILLA_API_KEY.