Skip to content
HuginnDB
esDownload

Documentation

Install it,
connect it,
and get to work.

Everything you need to run HuginnDB: the install command for your platform, what the first launch asks for, where profiles and credentials end up on disk, every flag the MCP connector takes, and how to build the whole thing from source. Commands are quoted from the app’s own docs — copy them as they are.

Install HuginnDB

A release publishes a Windows installer plus x86_64 Linux builds as .deb, .rpm and .AppImage. macOS is build-from-source, and the project is honest about those builds being unverified.

Windows

Windows 10 · 11

Download the NSIS installer from the latest release and run it. It registers HuginnDB with the Start menu and handles updates by reinstalling over the top.

windowsexe
HuginnDB_<version>_x64-setup.exe

First launch shows a SmartScreen warning — the binaries are not code-signed yet. See Troubleshooting below.

Linux — .deb

Debian · Ubuntu · Mint · Pop!_OS

Install through apt rather than dpkg so the runtime dependencies resolve on their own. Debian, Ubuntu, Mint and Pop!_OS.

debbash
sudo apt install ./HuginnDB_<version>_amd64.deb

Keep the leading ./ — without it apt looks for a package named HuginnDB in your configured repositories and fails.

Linux — .rpm

Fedora · openSUSE · RHEL family

Fedora, openSUSE and the RHEL family — RHEL itself, Rocky and AlmaLinux. dnf and zypper both take the same package, and both pull the runtime dependencies for you.

rpmbash
# Fedora, RHEL, Rocky, AlmaLinux
sudo dnf install ./HuginnDB-<version>-1.x86_64.rpm

# openSUSE
sudo zypper install ./HuginnDB-<version>-1.x86_64.rpm

The .rpm target is newer than the rest: if the release you are looking at has no .rpm asset yet, take the AppImage — it runs on all of these unchanged.

Linux — .AppImage

Any x86_64 distro

No install step at all: mark it executable and run it. Any x86_64 distribution, nothing written outside your home directory.

appimagebash
chmod +x HuginnDB_<version>_amd64.AppImage
./HuginnDB_<version>_amd64.AppImage

Built on Ubuntu 22.04, so it needs glibc 2.35 or newer. On an older distribution, build from source instead.

macOS

Build from source

There is no published macOS binary. The code compiles with the Xcode command-line tools and the same pnpm commands as everywhere else, but nobody verifies those builds — treat it as experimental.

macosbash
xcode-select --install
pnpm install && pnpm tauri:build

Install the prerequisites in Build from source first; the two lines here are only the macOS-specific part.

Replace <version> with the tag of the release you downloaded — the artifact names on the releases page already carry it.

DownloadWhat a release contains

Your first connection

HuginnDB opens with an empty connection list and nothing configured. Four steps and you are querying.

  1. Create a connection profile

    Pick the driver first — PostgreSQL, MySQL, SQLite, MongoDB or SQL Server. Each one gets its own dialog with the defaults that make sense for it; SQLite only wants a path to a file.

  2. The password goes to the keychain

    Save, and the password is handed straight to the OS keychain instead of being written into the profile. The profile on disk keeps host, port, database, username and the SSL toggle, and nothing else.

  3. Tunnel in if the host is remote

    A database that only answers on localhost is reachable through the SSH tunnel settings on the profile itself, so there is no second terminal to keep alive next to the app.

  4. Open the workspace and run something

    Expand the tree to a table to browse it, or open the SQL workspace and press Ctrl+Enter. Results land in the grid underneath, and double-clicking a cell opens it in the full editor.

Where HuginnDB keeps things

Two locations and that is the whole story: a config directory for profiles and logs, and the OS keychain for every secret.

Windows

Config directory
%APPDATA%\HuginnDB
Keychain backend
Credential Manager

Linux

Config directory
~/.config/HuginnDB
Keychain backend
libsecret

macOS

Config directory
~/Library/Application Support/HuginnDB
Keychain backend
Keychain

What a profile holds

Connection profiles are plain JSON in the config directory, so they are safe to read, diff and back up — because the half that matters is not in them:

  • host
  • port
  • database
  • username
  • ssl

What the keychain holds

Every secret, through the keyring crate: database passwords, SSH passphrases, AI API keys and shared-origin passphrases. They are resolved at the moment of use and never copied anywhere else, which is also why a working MCP client config contains no credentials at all.

The MCP audit log

Every write an agent runs — including one the database then rejects — is appended to a plain-text log in the same config directory. A write the connection’s policy refuses never runs, so it is not logged, and neither are reads. Tail it while an agent works if you want to watch exactly what it changes.

mcp-audit.log

Running several environments

There are no environment variables and no environment switcher. An environment is just another connection profile, and the MCP write policy is what keeps them apart — which means production is guarded by the same mechanism whether a human is clicking or an agent is querying.

  • Name profiles after the environment rather than the host: prod_analytics reads better than an IP address in the connection list, in a status chip, and in an agent’s tool output.
  • Leave production on the read-only policy and hand the data policy to staging only. The policy is re-read from disk on every write attempt, so tightening it takes effect immediately — no restart.
  • Expose only the profiles an agent actually needs. --connections is opt-in: a server started without it exposes nothing at all.
  • For a session where nothing should write whatever the per-connection policies say, start the connector with --read-only. It is a global kill switch.

Wiring up the MCP connector

huginndb-mcp is a headless stdio server installed as a sidecar beside the app. The MCP page carries the ready-to-paste snippet for each client; this is everything around them.

Four steps

  1. Open Preferences → MCP. The panel prints the resolved path of the sidecar binary on your machine — copy it from there instead of guessing where the installer put it.
  2. Tick the connections you want to expose and set a write policy for each one. Read-only is the default, and nothing is writable until you change it.
  3. Copy the generated config into your client: a single command for Claude Code, a JSON or TOML file for the others.
  4. Restart the client. Clients list the server’s tools when they connect, so if you cannot see run_query the server is not being launched at all.

Where each client keeps its config

The same server, declared in four different places.

Claude Code
claude mcp add huginndb -s user -- …
Claude Desktop
claude_desktop_config.json
Cursor
.cursor/mcp.json · ~/.cursor/mcp.json
Codex CLI
~/.codex/config.toml

Antigravity takes the same stdio JSON as Claude Desktop and Cursor. Check its own documentation for the file it reads — HuginnDB’s docs do not name one, so this page will not invent it.

Command-line flags

The generated config sets only --connections. The rest are for when you want a tighter session, and every one of them accepts either --flag value or --flag=value.

--connections <a,b,c>
Profile ids the server may reach. Opt-in: with none set, nothing is exposed.
--max-rows <n>default: 1000
Upper bound on the rows a single run_query or browse_table call returns.
--max-connections <n>default: 2
Connection budget for this server process.
--read-only[=true|false]default: false
Global kill switch: forces every connection to read-only, whatever its own policy says.
--allow-writesdeprecated
Deprecated and ignored. Write access comes from the per-connection policy, never from a flag.
Snippets, tool list and guard railsRead the docs

Build it yourself

MIT licensed: Rust backend, React frontend, Tauri 2 shell. This is also the only route to a macOS build.

Prerequisites

Node.js≥ 22.13
Frontend tooling. pnpm 11 needs this floor — on Node 20 the install aborts outright.
pnpm11.13.0
The only supported package manager, pinned in package.json so corepack picks the right one. There are no maintained npm or yarn lockfiles.
Ruststable
The Tauri backend. Install it through rustup.

System packages

Windows

Visual Studio Build Tools 2022 with the "Desktop development with C++" workload. WebView2 is already present on Windows 11; on Windows 10 install the Evergreen bootstrapper.

Linux

The WebKitGTK, GTK and libsecret development headers. This is the Debian and Ubuntu line — the package names differ on Fedora and Arch.

macOS

The Xcode command-line tools.

macosbash
xcode-select --install
linuxbash
sudo apt install -y \
  libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev \
  librsvg2-dev libsoup-3.0-dev libsecret-1-dev

Clone and build

tauri:dev gives you hot reload and takes five to ten minutes the first time, because it compiles the Rust side from scratch. tauri:build produces the installer.

src-tauri/target/release/bundle/

The bundles land there: an NSIS -setup.exe on Windows, and a .deb, an .rpm and an .AppImage on Linux.

View source on GitHub
huginndbbash
git clone https://github.com/Alexfp28/huginnDB.git
cd huginnDB
pnpm install
pnpm tauri:dev
pnpm tauri:build

When something does not work

The handful of things that actually go wrong on a first install, and what to do about each one.

  • Windows says "Windows protected your PC". Is that a malware warning?

    No. The binaries are not signed with an Authenticode certificate yet, and SmartScreen shows that dialog for any unsigned executable from a publisher it has not seen before. Click More info, then Run anyway. If you want to check first, the releases page publishes a SHA-256 digest you can compare against the file you downloaded. Code signing is on the roadmap.

  • The AppImage will not start on my distribution.

    It is built on Ubuntu 22.04, so it needs glibc 2.35 or newer, and the .deb has the same floor. On an older distribution the only route is building from source against your own system libraries.

  • On Linux it cannot save my password.

    The keychain needs a libsecret provider running — gnome-keyring, or KWallet with the libsecret bridge. Minimal window managers and headless machines often ship with neither, and without one there is nowhere for the password to go. Installing gnome-keyring and making sure it is unlocked at login fixes it.

  • Is there really no macOS download?

    Not a published one. The code builds on macOS and people run it, but nobody verifies those builds — shipping a binary would imply testing that is not happening. Build from source and treat it as experimental.

  • My agent cannot see the HuginnDB tools.

    Three usual causes: the client was never restarted, the path in the config is not the one Preferences → MCP prints, or --connections was left out — in which case the server does start and exposes nothing. Run the command yourself in a terminal: a launch failure prints there and is invisible inside the client.

  • An agent got a truncated result set.

    run_query and browse_table return at most 1000 rows unless --max-rows says otherwise. Raise it, or have the agent aggregate in SQL rather than pulling rows across — which is usually the better answer anyway.

Still stuck?

The README and the MCP reference in the repository go deeper than this page does. If neither covers it, an issue with your OS, the version and what you typed is genuinely useful — there is no support tier to route it to.

Open an issueRead the docs