Primeros Pasos

Requisitos Previos

Un cliente compatible con MCP — Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, Cursor, Windsurf, o cualquier otro host MCP
Un vault de Obsidian (o cualquier directorio de archivos Markdown) — consulta Estructura del Vault para ver el layout esperado
Opcional para delegación de tareas: cualquier endpoint /v1 compatible con OpenAI — un servicio alojado o un runtime en tu propia máquina. Necesitas su URL base, una credencial si la requiere y un id de modelo. Hive no nombra ningún proveedor.

Instalación

Un solo comando. Sin clonar, sin venv, sin archivos de configuración.

claude mcp add -s user hive -- uvx --upgrade hive-vault

Agrega a ~/.codex/config.toml:

[mcp_servers.hive-vault]
command = "uvx"
args = ["--upgrade", "hive-vault"]

gemini mcp add -s user hive-vault uvx -- --upgrade hive-vault

Agrega a .vscode/mcp.json en tu proyecto:

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"]
    }
  }
}

Agrega a ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "enabled": true
    }
  }
}

El flag --upgrade asegura que siempre obtengas la última versión de PyPI al iniciar cada sesión. uvx gestiona el entorno Python automáticamente.

Actualizar una instalación persistente

Las configuraciones con uvx anteriores resuelven la versión actual en cada nueva sesión. Si usas una instalación persistente para el modo daemon, actualízala de forma deliberada:

# Linux / macOS
uv tool upgrade hive-vault

# Windows (la versión es opcional; al omitirla se selecciona la última versión de PyPI)
hive self-upgrade [version]

En Windows, self-upgrade construye la nueva release junto a los archivos activos y cambia el runtime gestionado de forma atómica, sin modificar archivos retenidos por un proceso de Hive en ejecución. Abre una terminal nueva tras la primera actualización gestionada para disponer del launcher añadido a tu PATH de usuario. Inicia una nueva sesión MCP tras cualquier actualización; una sesión existente mantiene su proceso de servidor actual.

Primera Consulta

Una vez registrado, tu asistente de IA puede usar las herramientas de Hive. Prueba preguntando:

“Usa vault_list para ver mi vault”

El asistente llamará a vault_list() y listará todos los proyectos con recuento de archivos y atajos disponibles.

Configurar Ruta del Vault

Por defecto, Hive busca tu vault en ~/Projects/knowledge. Si esta ruta no existe, las herramientas de vault devolverán un error con instrucciones de configuración — el servidor sigue arrancando, así que las herramientas de worker permanecen disponibles.

Para apuntar Hive a tu vault:

claude mcp add -s user hive -e VAULT_PATH=/ruta/a/tu/vault -- uvx --upgrade hive-vault

[mcp_servers.hive-vault]
command = "uvx"
args = ["--upgrade", "hive-vault"]

[mcp_servers.hive-vault.env]
VAULT_PATH = "/ruta/a/tu/vault"

gemini mcp add -s user -e VAULT_PATH=/ruta/a/tu/vault hive-vault uvx -- --upgrade hive-vault

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"],
      "env": {
        "VAULT_PATH": "/ruta/a/tu/vault"
      }
    }
  }
}

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "environment": {
        "VAULT_PATH": "/ruta/a/tu/vault"
      },
      "enabled": true
    }
  }
}

Configurar Worker (Opcional)

Para habilitar la delegación de tareas, apunta Hive a un único endpoint compatible con OpenAI con HIVE_WORKER_BASE_URL, HIVE_WORKER_API_KEY y HIVE_WORKER_MODEL. Sin URL base el worker queda deshabilitado y delegate_task indica al host que gestione la tarea por sí mismo:

# Exporta antes HIVE_WORKER_API_KEY desde tu gestor de secretos.
claude mcp add -s user hive \
  -e VAULT_PATH=/ruta/a/tu/vault \
  -e HIVE_WORKER_BASE_URL=https://api.your-provider.example/v1 \
  -e HIVE_WORKER_API_KEY="$HIVE_WORKER_API_KEY" \
  -e HIVE_WORKER_MODEL=<id-del-modelo> \
  -- uvx --upgrade hive-vault

[mcp_servers.hive-vault]
command = "uvx"
args = ["--upgrade", "hive-vault"]

[mcp_servers.hive-vault.env]
VAULT_PATH = "/ruta/a/tu/vault"
HIVE_WORKER_BASE_URL = "https://api.your-provider.example/v1"
HIVE_WORKER_API_KEY = "<tu-clave>"
HIVE_WORKER_MODEL = "<id-del-modelo>"

# Exporta antes HIVE_WORKER_API_KEY desde tu gestor de secretos.
gemini mcp add -s user \
  -e VAULT_PATH=/ruta/a/tu/vault \
  -e HIVE_WORKER_BASE_URL=https://api.your-provider.example/v1 \
  -e HIVE_WORKER_API_KEY="$HIVE_WORKER_API_KEY" \
  -e HIVE_WORKER_MODEL=<id-del-modelo> \
  hive-vault uvx -- --upgrade hive-vault

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"],
      "env": {
        "VAULT_PATH": "/ruta/a/tu/vault",
        "HIVE_WORKER_BASE_URL": "https://api.your-provider.example/v1",
        "HIVE_WORKER_API_KEY": "<tu-clave>",
        "HIVE_WORKER_MODEL": "<id-del-modelo>"
      }
    }
  }
}

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "environment": {
        "VAULT_PATH": "/ruta/a/tu/vault",
        "HIVE_WORKER_BASE_URL": "https://api.your-provider.example/v1",
        "HIVE_WORKER_API_KEY": "<tu-clave>",
        "HIVE_WORKER_MODEL": "<id-del-modelo>"
      },
      "enabled": true
    }
  }
}

Consulta Configuración para ver todas las variables de entorno.

Verificar

Ejecuta un chequeo de salud:

“Usa vault_health para comprobar mi vault”

Deberías ver recuentos de proyectos, archivos y métricas de obsolescencia para cada proyecto en tu vault.

Siguientes Pasos

Casos de Uso — flujos de trabajo reales con Hive
Configuración — referencia completa de variables de entorno
Herramientas de Vault — todas las herramientas de vault
Herramientas de Worker — delegación de tareas y estado del worker
Estructura del Vault — cómo organizar tu vault
Solución de Problemas — problemas comunes y soluciones