Skip to content

Use DBGorilla from the command line

Last updated

View as Markdown

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.

You need Node.js 20 or newer.

Terminal window
npm install -g mcporter
mcporter --version
0.9.0

mcporter keeps its settings in config/mcporter.json under the folder you run it from. Create one folder and always run mcporter from there.

Terminal window
mkdir ~/dbgorilla-cli && cd ~/dbgorilla-cli
mcporter config add dbgorilla --url https://app.dbgorilla.com/mcp/readonly
Added 'dbgorilla' to /home/you/dbgorilla-cli/config/mcporter.json

Then 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)”
Terminal window
mcporter auth dbgorilla

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

Use this for a server or script where a browser is not practical.

To get your key in DBGorilla:

  1. Click your name in the sidebar to open the user menu.
  2. Choose Profile.
  3. Open the MCP Access tab.
  4. 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:

Terminal window
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.

List the tools:

Terminal window
mcporter list dbgorilla
dbgorilla
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.

Terminal window
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:

Terminal window
C=9bc21246-e089-5391-ad14-5d21d77197d8

list_databases is a different tool: it lists databases DBGorilla hosts for you. For your own databases, use discover_components.

Terminal window
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:

Terminal window
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 change
In the external inventory-writing SQL/script workflow for database `storefront`, remove the deliberate
database sleep from the transaction responsible for the observed blocking session `13567`. If pacing is
required, perform it only **after the entire inventory/order transaction has committed** ...

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

Terminal window
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=3
Top 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:

Terminal window
mcporter call dbgorilla.investigate_workload component_id=$C fingerprint=44fc11468e033234 \
start=2026-11-07T00:00:00Z end=2026-11-07T15:57:45Z
Workload 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 | ...
...
Terminal window
mcporter config logout dbgorilla
Cleared 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.