# dbhawk

Lets an assistant reach DBHawk datasources: browse schemas, run governed queries, and turn plain questions into SQL.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: Datasparc
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Datasparc/dbhawk-mcp-plugin
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/dbhawk

## What it does

dbhawk sits on top of the DBHawk REST surface under `/api/v2/mcp/**`. Your assistant only sees datasources assigned to the signed-in user, and every statement is classified and matched against the MCP tier of that user's groups. The default tier is read-only, so writes to data or schema happen only where the tier permits. DBHawk AI adds text-to-SQL, query optimization and formatting.

Auth works two ways. Leave `DBHAWK_TOKEN` empty and the first tool call opens the DBHawk sign-in page in your browser — password, LDAP, 2FA or SSO, whichever your DBHawk supports. Approve once and a refresh token is kept in your user profile (`%APPDATA%\dbhawk-mcp` on Windows, `~/Library/Application Support/dbhawk-mcp` on macOS, `~/.config/dbhawk-mcp` on Linux). That path needs DBHawk 7.0.1 with the MCP connector. A personal token `dbh_<id>.<secret>` is not a JWT, so the server trades it for a short-lived JWT at `POST /api/v2/auth/token/exchange`, caches it, refreshes it before expiry and retries once on a `401`. The token owner needs `ACCESS_TO_DATA`.

The repo ships a self-contained bundle at `dist/dbhawk-mcp.mjs` with dependencies inlined, so a plain `git clone` runs without installing packages. In Claude the settings are declared as `userConfig`, which means the token is masked on entry and lands in secure storage rather than `settings.json`.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `DBHAWK_BASE_URL`, `DBHAWK_TOKEN`, `DBHAWK_DEFAULT_DATASOURCE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env DBHAWK_BASE_URL=<DBHAWK_BASE_URL> --env DBHAWK_TOKEN=<DBHAWK_TOKEN> --env DBHAWK_DEFAULT_DATASOURCE=<DBHAWK_DEFAULT_DATASOURCE> --transport stdio dbhawk -- npx -y @dbhawk/mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add dbhawk --env DBHAWK_BASE_URL=<DBHAWK_BASE_URL> --env DBHAWK_TOKEN=<DBHAWK_TOKEN> --env DBHAWK_DEFAULT_DATASOURCE=<DBHAWK_DEFAULT_DATASOURCE> -- npx -y @dbhawk/mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "dbhawk": {
            "command": "npx",
            "args": [
                "-y",
                "@dbhawk/mcp"
            ],
            "env": {
                "DBHAWK_BASE_URL": "<DBHAWK_BASE_URL>",
                "DBHAWK_TOKEN": "<DBHAWK_TOKEN>",
                "DBHAWK_DEFAULT_DATASOURCE": "<DBHAWK_DEFAULT_DATASOURCE>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "dbhawk": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@dbhawk/mcp"
            ],
            "env": {
                "DBHAWK_BASE_URL": "<DBHAWK_BASE_URL>",
                "DBHAWK_TOKEN": "<DBHAWK_TOKEN>",
                "DBHAWK_DEFAULT_DATASOURCE": "<DBHAWK_DEFAULT_DATASOURCE>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e DBHAWK_BASE_URL=<DBHAWK_BASE_URL> -e DBHAWK_TOKEN=<DBHAWK_TOKEN> -e DBHAWK_DEFAULT_DATASOURCE=<DBHAWK_DEFAULT_DATASOURCE> dbhawk npx -y @dbhawk/mcp
```
Replace <…> with your own values

## When to use it
- see which DBHawk datasources a user can reach
- inspect schemas, tables and columns before writing a query
- run a query with access control and column masking applied
- turn a plain-language question into SQL with DBHawk AI
- check whether the MCP tier allows a data change

## Example prompts
- List the datasources I have access to in DBHawk
- Show the tables and columns in schema `public` on datasource `sales`
- Write SQL for: how many orders came in last month

## Similar
- [database-optimization](https://affpapa.org/en/nevibecode/agents/database-optimization.md) — subagent · 3924 installs
- [planetscale-mcp-agent-operating-model](https://affpapa.org/en/nevibecode/skills/planetscale-mcp-agent-operating-model.md) — skill · 2400 installs
- [planetscale-pscale-cli-automation](https://affpapa.org/en/nevibecode/skills/planetscale-pscale-cli-automation.md) — skill · 1700 installs
- [attach-db](https://affpapa.org/en/nevibecode/skills/attach-db.md) — skill · 1000 installs
- [migrate-create](https://affpapa.org/en/nevibecode/skills/migrate-create.md) — skill · 729 installs
- [dbhub](https://affpapa.org/en/nevibecode/skills/dbhub.md) — skill · 644 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md