dbhawk — Claude Code MCP server: DBHawk data access
Lets an assistant reach DBHawk datasources: browse schemas, run governed queries, and turn plain questions into SQL.
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/mcpWhat dbhawk 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.
What it helps with
- 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 for the agent
- List the datasources I have access to in DBHawk
- Show the tables and columns in schema
publicon datasourcesales - Write SQL for: how many orders came in last month
How to install dbhawk
Platform CLI
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/mcpReplace <…> with your own values
Platform CLI
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/mcpReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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/mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about dbhawk
How do I install dbhawk in Claude Code?
Run claude mcp add dbhawk -e DBHAWK_BASE_URL=<DBHAWK_BASE_URL> -e DBHAWK_TOKEN=<DBHAWK_TOKEN> -- npx -y @dbhawk/mcp, then confirm the tools are live with /mcp.
What does dbhawk do?
It gives an assistant access to DBHawk: datasource listing, schema and column browsing, queries under the user's own permissions, and text-to-SQL through DBHawk AI.
Do I need a DBHawk token for it to work?
No. With DBHAWK_TOKEN empty the server opens the DBHawk sign-in in your browser on the first call and stores a refresh token in your profile. That requires DBHawk 7.0.1 with the MCP connector.
