Documentación
Instálalo,
conéctalo
y a trabajar.
Todo lo necesario para tener HuginnDB funcionando: el comando de instalación de tu plataforma, qué te pide el primer arranque, dónde acaban los perfiles y las credenciales en el disco, todos los flags del conector MCP y cómo compilarlo entero desde el código fuente. Los comandos están citados de la documentación de la propia app: cópialos tal cual.
Instalar HuginnDB
Cada release publica un instalador de Windows y builds de Linux x86_64 en .deb, .rpm y .AppImage. En macOS toca compilar, y el proyecto reconoce abiertamente que esas compilaciones no están verificadas.
Windows
Windows 10 · 11
Descarga el instalador NSIS de la última release y ejecútalo. Registra HuginnDB en el menú de inicio y se actualiza reinstalando encima.
HuginnDB_<version>_x64-setup.exeEl primer arranque muestra un aviso de SmartScreen: los binarios todavía no están firmados. Lo tienes explicado en Problemas, más abajo.
Linux — .deb
Debian · Ubuntu · Mint · Pop!_OS
Instálalo con apt en vez de dpkg para que las dependencias de ejecución se resuelvan solas. Debian, Ubuntu, Mint y Pop!_OS.
sudo apt install ./HuginnDB_<version>_amd64.debNo quites el ./ del principio: sin él, apt busca un paquete llamado HuginnDB en tus repositorios y falla.
Linux — .rpm
Fedora · openSUSE · familia RHEL
Fedora, openSUSE y la familia RHEL: RHEL, Rocky y AlmaLinux. dnf y zypper aceptan el mismo paquete y los dos resuelven las dependencias de ejecución por ti.
# Fedora, RHEL, Rocky, AlmaLinux
sudo dnf install ./HuginnDB-<version>-1.x86_64.rpm
# openSUSE
sudo zypper install ./HuginnDB-<version>-1.x86_64.rpmEl target .rpm es más reciente que el resto: si la release que estás viendo todavía no tiene un .rpm, coge el AppImage — funciona igual en todas esas distribuciones.
Linux — .AppImage
Cualquier distro x86_64
Sin instalación de ningún tipo: le das permiso de ejecución y lo lanzas. Cualquier distribución x86_64, sin escribir nada fuera de tu carpeta personal.
chmod +x HuginnDB_<version>_amd64.AppImage
./HuginnDB_<version>_amd64.AppImageEstá compilado en Ubuntu 22.04, así que necesita glibc 2.35 o superior. En una distribución más antigua, compila desde el código fuente.
macOS
Compilar desde el código
No hay binario publicado para macOS. El código compila con las herramientas de línea de comandos de Xcode y los mismos comandos de pnpm que en el resto de plataformas, pero nadie verifica esas builds: trátalo como experimental.
xcode-select --install
pnpm install && pnpm tauri:buildInstala primero los requisitos de la sección de compilación; estas dos líneas son solo la parte específica de macOS.
Sustituye <version> por la etiqueta de la release que has descargado — los nombres de los artefactos en la página de releases ya la llevan.
Tu primera conexión
HuginnDB abre con la lista de conexiones vacía y nada configurado. Cuatro pasos y ya estás consultando.
Crea un perfil de conexión
Primero eliges el driver: PostgreSQL, MySQL, SQLite, MongoDB o SQL Server. Cada uno tiene su propio diálogo con los valores por defecto que le corresponden; SQLite solo quiere la ruta de un fichero.
La contraseña va al llavero
Al guardar, la contraseña pasa directamente al llavero del sistema en vez de escribirse en el perfil. En el disco, el perfil guarda host, puerto, base de datos, usuario y el interruptor de SSL, y nada más.
Haz túnel si el host es remoto
Una base de datos que solo responde en localhost queda accesible con los ajustes de túnel SSH del propio perfil, así que no hay una segunda terminal que mantener viva al lado de la app.
Abre el workspace y ejecuta algo
Despliega el árbol hasta una tabla para navegarla, o abre el workspace SQL y pulsa Ctrl+Enter. Los resultados aparecen en la tabla de abajo, y al hacer doble clic en una celda se abre en el editor completo.
Dónde guarda las cosas HuginnDB
Dos sitios y ya está: un directorio de configuración para los perfiles y los logs, y el llavero del sistema para todos los secretos.
Windows
- Directorio de configuración
%APPDATA%\HuginnDB- Llavero del sistema
- Credential Manager
Linux
- Directorio de configuración
~/.config/HuginnDB- Llavero del sistema
- libsecret
macOS
- Directorio de configuración
~/Library/Application Support/HuginnDB- Llavero del sistema
- Keychain
Qué contiene un perfil
Los perfiles de conexión son JSON plano en el directorio de configuración, así que puedes leerlos, versionarlos y respaldarlos sin miedo — precisamente porque la mitad importante no está ahí:
hostportdatabaseusernamessl
Qué contiene el llavero
Todos los secretos, a través del crate keyring: contraseñas de base de datos, frases de paso SSH, claves de API de IA y frases de paso de orígenes compartidos. Se resuelven en el momento de usarlas y no se copian a ningún otro sitio, que es también la razón por la que una configuración de cliente MCP que funciona no contiene ninguna credencial.
El log de auditoría de MCP
Cada escritura que ejecuta un agente — incluida una que luego rechace la base de datos — se añade a un log de texto plano en ese mismo directorio de configuración. Una escritura que la política de la conexión rechaza no llega a ejecutarse, así que no se registra, y las lecturas tampoco. Déjalo abierto con tail mientras trabaja un agente si quieres ver exactamente qué cambia.
mcp-audit.log
Trabajar con varios entornos
No hay variables de entorno ni selector de entorno. Un entorno es simplemente otro perfil de conexión, y lo que los separa es la política de escritura de MCP — con lo cual producción queda protegida por el mismo mecanismo tanto si hay una persona haciendo clic como si hay un agente consultando.
- Nombra los perfiles por el entorno y no por el host: prod_analytics se lee mucho mejor que una IP en la lista de conexiones, en una etiqueta de estado y en la salida de las herramientas de un agente.
- Deja producción en solo lectura y dale la política de datos únicamente a staging. La política se vuelve a leer del disco en cada intento de escritura, así que restringirla tiene efecto inmediato, sin reiniciar nada.
- Expón solo los perfiles que el agente necesita de verdad. --connections es opt-in: un servidor arrancado sin ese flag no expone absolutamente nada.
- Para una sesión en la que no se debe escribir nada, digan lo que digan las políticas de cada conexión, arranca el conector con --read-only. Es un interruptor global.
Conectar el servidor MCP
huginndb-mcp es un servidor stdio sin interfaz que se instala como sidecar junto a la app. La página de MCP tiene el fragmento listo para pegar de cada cliente; esto es todo lo que hay alrededor.
Cuatro pasos
- Abre Preferencias → MCP. El panel imprime la ruta real del binario sidecar en tu máquina: cópiala de ahí en vez de adivinar dónde lo ha dejado el instalador.
- Marca las conexiones que quieres exponer y asigna una política de escritura a cada una. Solo lectura es la opción por defecto y nada es escribible hasta que tú lo cambies.
- Copia la configuración generada en tu cliente: un solo comando para Claude Code, un fichero JSON o TOML para los demás.
- Reinicia el cliente. Los clientes listan las herramientas del servidor al conectarse, así que si no ves run_query es que el servidor no se está arrancando en absoluto.
Dónde guarda su configuración cada cliente
El mismo servidor, declarado en cuatro sitios distintos.
- 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 usa el mismo JSON stdio que Claude Desktop y Cursor. Consulta su propia documentación para saber qué fichero lee: la documentación de HuginnDB no lo nombra, y esta página no se lo va a inventar.
Flags de línea de comandos
La configuración generada solo pone --connections. El resto están para cuando quieras una sesión más restringida, y todos aceptan tanto --flag valor como --flag=valor.
--connections <a,b,c>- Ids de los perfiles a los que puede llegar el servidor. Es opt-in: si no pones ninguno, no se expone nada.
--max-rows <n>por defecto: 1000- Límite de filas que devuelve una sola llamada a run_query o browse_table.
--max-connections <n>por defecto: 2- Presupuesto de conexiones de este proceso del servidor.
--read-only[=true|false]por defecto: false- Interruptor global: fuerza todas las conexiones a solo lectura, diga lo que diga la política de cada una.
--allow-writesobsoleto- Obsoleto y se ignora. El acceso de escritura viene de la política de cada conexión, nunca de un flag.
Compílalo tú mismo
Licencia MIT: backend en Rust, frontend en React, envoltorio Tauri 2. Es también el único camino para tener una build de macOS.
Requisitos
- Node.js≥ 22.13
- Herramientas del frontend. pnpm 11 necesita este mínimo: con Node 20 la instalación aborta.
- pnpm11.13.0
- El único gestor de paquetes soportado, fijado en package.json para que corepack use el correcto. No hay lockfiles de npm ni de yarn mantenidos.
- Ruststable
- El backend de Tauri. Instálalo con rustup.
Paquetes del sistema
Windows
Visual Studio Build Tools 2022 con la carga de trabajo "Desarrollo para el escritorio con C++". WebView2 ya viene en Windows 11; en Windows 10 hay que instalar el bootstrapper Evergreen.
Linux
Las cabeceras de desarrollo de WebKitGTK, GTK y libsecret. Esta es la línea de Debian y Ubuntu — en Fedora y Arch los paquetes se llaman de otra forma.
macOS
Las herramientas de línea de comandos de Xcode.
xcode-select --installsudo 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-devClonar y compilar
tauri:dev te da recarga en caliente y tarda entre cinco y diez minutos la primera vez, porque compila todo el lado de Rust desde cero. tauri:build genera el instalador.
src-tauri/target/release/bundle/
Ahí es donde aparecen los bundles: un -setup.exe de NSIS en Windows, y un .deb, un .rpm y un .AppImage en Linux.
Ver el código en GitHubgit clone https://github.com/Alexfp28/huginnDB.git
cd huginnDB
pnpm install
pnpm tauri:dev
pnpm tauri:buildCuando algo no funciona
Las pocas cosas que de verdad fallan en una primera instalación, y qué hacer con cada una.
Windows dice "Windows protegió su PC". ¿Es un aviso de malware?
No. Los binarios todavía no están firmados con un certificado Authenticode, y SmartScreen muestra ese diálogo con cualquier ejecutable sin firmar de un editor que no conoce. Pulsa Más información y luego Ejecutar de todas formas. Si prefieres comprobarlo antes, la página de releases publica un hash SHA-256 que puedes comparar con el fichero descargado. La firma de código está en el roadmap.
El AppImage no arranca en mi distribución.
Está compilado en Ubuntu 22.04, así que necesita glibc 2.35 o superior, y el .deb tiene el mismo mínimo. En una distribución más antigua el único camino es compilar desde el código fuente contra tus propias librerías del sistema.
En Linux no consigue guardar mi contraseña.
El llavero necesita un proveedor de libsecret en marcha: gnome-keyring, o KWallet con el puente de libsecret. Los gestores de ventanas minimalistas y las máquinas sin escritorio a menudo no traen ninguno, y sin él no hay dónde guardar la contraseña. Instalar gnome-keyring y asegurarte de que se desbloquea al iniciar sesión lo resuelve.
¿De verdad no hay descarga para macOS?
Publicada, no. El código compila en macOS y hay gente que lo usa, pero nadie verifica esas builds, y publicar un binario daría a entender unas pruebas que no existen. Compila desde el código fuente y trátalo como experimental.
Mi agente no ve las herramientas de HuginnDB.
Tres causas habituales: no se ha reiniciado el cliente, la ruta de la configuración no es la que imprime Preferencias → MCP, o falta --connections — en ese caso el servidor sí arranca y no expone nada. Ejecuta el comando tú mismo en una terminal: un fallo al arrancar se imprime ahí y es invisible desde dentro del cliente.
Un agente ha recibido un resultado truncado.
run_query y browse_table devuelven como máximo 1000 filas salvo que --max-rows diga otra cosa. Súbelo, o haz que el agente agregue en SQL en lugar de traerse las filas — que además suele ser la mejor respuesta.
¿Sigues atascado?
El README y la referencia de MCP del repositorio entran en más detalle que esta página. Si ninguno lo cubre, abrir un issue con tu sistema operativo, la versión y lo que has escrito es de verdad útil: no hay un plan de soporte al que derivarlo.