Heimdall

Heimdall es un servicio ligero para administrar servidores MCP locales y se instala con un solo comando npx . Se pueden autorizar herramientas específicas del servidor MCP para sus clientes MCP, y la misma configuración es accesible para todos los clientes MCP de su dispositivo.

Instalación

⚠️ NOTA: Recomendamos encarecidamente realizar una copia de seguridad de la configuración del servidor MCP antes de la instalación para protegerse contra la pérdida inesperada de credenciales.

El script de configuración realiza algunas acciones clave:

Mueve el JSON de configuración mcpServers desde la ruta que especifique a ~/.heimdall/config.json
Inserta una única configuración para heimdall en lugar de la ruta de configuración anterior mcpServers
Inicializa los controles en ~/.heimdall/controls.json para autorizar todos los métodos en todos los servidores actuales

Consulte Configuración para conocer los pasos para modificar ~/.heimdall/controls.json para limitar las herramientas autorizadas para un servidor determinado y agregar nuevos servidores a ~/.heimdall/config.json .

Vía NPX (recomendado)

Ejecutar el script de instalación (genera una configuración vacía si no se proporciona ninguna ruta):

npx @shinzolabs/heimdall setup <optional: path/to/current/config.json>

A través de una instancia local

Descargar el paquete:

git clone https://github.com/shinzo-labs/heimdall.git

Instalar y crear dependencias:

cd heimdall && pnpm i && pnpm build

Ejecutar el script de instalación (genera una configuración vacía si no se proporciona ninguna ruta):

pnpm run setup <optional: path/to/current/config.json> <optional: path to `index.js` file in local Heimdall instance, ex. `/path/to/local/heimdall/dist/index.js`>

Configuración

Editar lista de servidores

Para agregar o actualizar los servidores disponibles, simplemente actualice la configuración en ~/.heimdall/config.json como su archivo JSON de configuración habitual mcpServers . Tenga en cuenta que no verá las herramientas para los nuevos servidores a través de Heimdall a menos que también agregue el servidor y las herramientas autorizadas a ~/.heimdall/controls.json .

Editar herramientas autorizadas

Para agregar herramientas autorizadas a un servidor nuevo o existente, agréguelas según sea necesario a ~/.heimdall/controls.json y Heimdall actualizará su configuración interna después de unos segundos. Si su cliente MCP admite el almacenamiento en caché dinámico de la lista de herramientas, debería ver que las herramientas autorizadas se actualizan automáticamente. Otros clientes (por ejemplo, Claude Desktop) podrían requerir un reinicio para ver las nuevas herramientas.

Este es el esquema para ~/.heimdall/controls.json :

{
  "authorizedMcpServers": {
    "server1": {
      "authorizedTools": [
        "tool1",
        "tool2",
        ...
      ]
    },
    "server2": {
      "authorizedTools": [
        "tool1",
        "tool2",
        ...
      ]
    }

Múltiples clientes MCP

Si ejecuta varios clientes MCP en su dispositivo, puede configurar el siguiente config.json para cada nuevo cliente para habilitar las mismas herramientas autorizadas en todos ellos (asumiendo que Heimdall ya se ha configurado en el dispositivo):

{
  "mcpServers": {
    "heimdall": {
      "command": "npx",
      "args": [
        "@shinzolabs/heimdall"
      ]
    }
  }
}

Solución de problemas

Herramientas disponibles

Algunos clientes de MCP tienen límites en la cantidad de herramientas disponibles para los agentes en un momento dado. Por ejemplo, Cursor solo admite hasta 40 herramientas en todos los servidores, por lo que la suma de authorizedTools en controls.json no puede superar esta cantidad.

Explotación florestal

Para consultar los registros de las instancias en ejecución, acceda a ~/.heimdall/logs . Los registros de cada instancia de Heimdall y servidores secundarios de cada cliente MCP se almacenan en directorios separados, identificados mediante UUID aleatorios.

Procesos de niños huérfanos

Si su cliente MCP se cierra inesperadamente o no envía la señal SIGTERM correcta a Heimdall antes del cierre, es posible que aún haya procesos node huérfanos (y npm ) ejecutándose en su dispositivo. Por el momento, debe forzar su detención manual. Si no hay otros procesos node sensibles ejecutándose en su dispositivo, puede usar este comando como limpieza posterior:

pkill -aif node

Contribuyendo

Se agradecen y animamos las contribuciones. Para cualquier pregunta, comentario o inquietud, contacte con austin@shinzolabs.com .

Integrations