Dbhawk MCP server

DBHawk MCP — Claude Code plugin + demo connector

Gives an AI assistant read-only access to DBHawk: list the datasources a user is assigned, browse schema/tables/columns, run read-only queries (with the user's access control and column masking applied), and use HawkAI text-to-SQL / optimize / format.

It's a thin bridge over the existing DBHawk REST surface at /api/v2/mcp/**. No write path exists; DBHawk rejects any statement that modifies data or schema, whatever role the token owner has.

Auth is two steps. DBHAWKTOKEN is a personal token (dbh.), not a JWT — the MCP endpoints won't accept it directly. On its first call the server exchanges it for a short-lived JWT at POST /api/v2/auth/token/exchange (sending the personal token in the X-API-Token header), caches that JWT, and sends it as the Bearer for every /api/v2/mcp/** call. When the JWT expires the next call gets a 401, and the server re-exchanges and retries once — transparent to you.

dbhawk-mcp-plugin/                 <- this folder = a Claude Code "marketplace" (push it to git)
├── .claude-plugin/marketplace.json
└── dbhawk/                        <- the actual plugin (installed by users)
    ├── .claude-plugin/plugin.json
    ├── .mcp.json                  <- declares the "dbhawk" stdio MCP server
    └── mcp-server/
        ├── index.js               <- source
        ├── package.json           <- build tooling (maintainers only)
        └── dist/dbhawk-mcp.mjs    <- COMMITTED self-contained bundle (what users run; no npm install)

The bundle in dist/ inlines every dependency, so a bare git clone runs with zero install — that's what makes /plugin install work.

For users — install

Claude Code (from the marketplace)

Once this repo is on GitHub (see Publish below), point Claude Code at it and install:

/plugin marketplace add datasparc/dbhawk-mcp-plugin
/plugin install dbhawk@dbhawk-marketplace

dbhawk is the plugin name, dbhawk-marketplace is the marketplace name (from marketplace.json). Then set the connection (see Configure) and check the tools are live with /mcp.

Prefer to try it without a git host? Load the local folder for one session:

claude --plugin-dir ./dbhawk-mcp-plugin/dbhawk

Claude Desktop (extension, .mcpb) — recommended

Claude Desktop installs this as a Desktop Extension with a proper GUI settings form (no JSON editing). It's the same MCP server, packaged as an .mcpb bundle.

(or just drag the .mcpb onto the Extensions window).

1. Download dbhawk-.mcpb from the Releases page.
2. In Claude Desktop: Settings → Extensions → Advanced settings → Install and pick the file

Default Datasource (optional) — and save.

1. Fill in the form — DBHawk Base URL, API Token (masked; stored in your OS keychain),

Claude Desktop does not auto-update file-installed extensions: to upgrade, download the newer .mcpb and install it again. This is independent of the Claude Code plugin — you don't need the marketplace plugin installed.

Claude Desktop (manual config, advanced)

Prefer to wire it by hand instead of the .mcpb? Point Desktop at the bundle with an absolute path. Edit claudedesktopconfig.json (Windows: %APPDATA%\Claude\claudedesktopconfig.json, macOS: ~/Library/Application Support/Claude/claudedesktopconfig.json):

{
  "mcpServers": {
    "dbhawk": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\...\\dbhawk-mcp-plugin\\dbhawk\\mcp-server\\dist\\dbhawk-mcp.mjs"],
      "env": {
        "DBHAWK_BASE_URL": "https://demo.dbhawk.example.com",
        "DBHAWK_TOKEN": "PASTE_MCP_TOKEN_HERE",
        "DBHAWK_DEFAULT_DATASOURCE": ""
      }
    }
  }
}

Restart Claude Desktop fully (including the tray icon).

Configure

Shortened. The full README is on GitHub.