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:
  • Ollama ejecutándose localmente — descarga un modelo con ollama pull qwen2.5-coder:7b
  • Cuenta en OpenRouter — crea una API key en openrouter.ai/keys (tier gratuito disponible)

Instalación

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

Usa scope de usuario

Registra siempre Hive a nivel de usuario (no de proyecto) para que funcione en todos tus proyectos. Ese es el objetivo — un vault, todos los proyectos.

• Claude Code: flag -s user
• Gemini CLI: flag -s user
• Codex CLI / Copilot / OpenCode: los archivos de config ya son a nivel de usuario (~/.codex/config.toml, ~/.config/opencode/opencode.jsonc) o se pueden agregar a la configuración de usuario de VS Code

Claude Code

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

Codex CLI

Agrega a ~/.codex/config.toml:

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

Gemini CLI

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

Copilot (VS Code)

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

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

OpenCode

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 Code

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

Codex CLI

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

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

Gemini CLI

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

Copilot (VS Code)

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

OpenCode

{
  "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 a modelos más baratos:

Claude Code

claude mcp add -s user hive \
  -e VAULT_PATH=/ruta/a/tu/vault \
  -e HIVE_OLLAMA_ENDPOINT=http://tu-ollama:11434 \
  -e OPENROUTER_API_KEY=sk-or-... \
  -- uvx --upgrade hive-vault

Codex CLI

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

[mcp_servers.hive-vault.env]
VAULT_PATH = "/ruta/a/tu/vault"
HIVE_OLLAMA_ENDPOINT = "http://tu-ollama:11434"
OPENROUTER_API_KEY = "sk-or-..."

Gemini CLI

gemini mcp add -s user \
  -e VAULT_PATH=/ruta/a/tu/vault \
  -e HIVE_OLLAMA_ENDPOINT=http://tu-ollama:11434 \
  -e OPENROUTER_API_KEY=sk-or-... \
  hive-vault uvx -- --upgrade hive-vault

Copilot (VS Code)

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"],
      "env": {
        "VAULT_PATH": "/ruta/a/tu/vault",
        "HIVE_OLLAMA_ENDPOINT": "http://tu-ollama:11434",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

OpenCode

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "environment": {
        "VAULT_PATH": "/ruta/a/tu/vault",
        "HIVE_OLLAMA_ENDPOINT": "http://tu-ollama:11434",
        "OPENROUTER_API_KEY": "sk-or-..."
      },
      "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 enrutamiento
• Estructura del Vault — cómo organizar tu vault
• Solución de Problemas — problemas comunes y soluciones