Hive Vault — Claude Code MCP server for Obsidian vaults
Gives your coding assistant on-demand access to an Obsidian vault instead of loading everything up front. Useful when project context lives in markdown files.
claude mcp add --env VAULT_PATH=<VAULT_PATH> --env HIVE_OLLAMA_ENDPOINT=<HIVE_OLLAMA_ENDPOINT> --env OPENROUTER_API_KEY=<OPENROUTER_API_KEY> --env HIVE_VAULT_SCOPES=<HIVE_VAULT_SCOPES> --transport stdio hive-vault -- uvx hive-vaultWhat Hive Vault does
The server exposes 17 tools, 5 resources and 4 prompts for working with an Obsidian vault. It queries what a task needs rather than dumping the whole vault into context. Knowledge stays in the vault, so a new session does not start from nothing.
You need Python 3.12+ and a directory of markdown files. Hive starts fine without VAULT_PATH; vault tools just return an error until you set it, so installing first and configuring later works. With git initialised inside the vault, vault_write and vault_patch commit each change. Without it, files still land on disk and only the commit is skipped. delegate_task and capture_lesson call an OpenAI-compatible /v1 endpoint configured through HIVE_WORKER_BASE_URL, HIVE_WORKER_API_KEY and HIVE_WORKER_MODEL.
An optional daemon mode runs one long-lived hive serve process that owns the vault, with stdio sessions relaying through hive client. The default endpoint is a per-user port picked from 49152..65535; override it with HIVE_DAEMON_PORT in the daemon and in every client environment. Until issue #456 is resolved, daemon mode does not belong on untrusted multi-user hosts.
What it helps with
- pull a specific note out of an Obsidian vault on request
- save a note into the vault from inside a session
- patch an existing markdown file without opening an editor
- commit vault changes at the end of a session
- hand a task to a worker through an OpenAI-compatible endpoint
Example prompts for the agent
- Use
vault_listto show me my vault - Find notes about the project architecture in my vault
- Write the session summary to the vault and commit it
How to install Hive Vault
Platform CLI
claude mcp add --env VAULT_PATH=<VAULT_PATH> --env HIVE_OLLAMA_ENDPOINT=<HIVE_OLLAMA_ENDPOINT> --env OPENROUTER_API_KEY=<OPENROUTER_API_KEY> --env HIVE_VAULT_SCOPES=<HIVE_VAULT_SCOPES> --transport stdio hive-vault -- uvx hive-vaultReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hive-vault <command>
Platform CLI
codex mcp add hive-vault --env VAULT_PATH=<VAULT_PATH> --env HIVE_OLLAMA_ENDPOINT=<HIVE_OLLAMA_ENDPOINT> --env OPENROUTER_API_KEY=<OPENROUTER_API_KEY> --env HIVE_VAULT_SCOPES=<HIVE_VAULT_SCOPES> -- uvx hive-vaultReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hive-vault <command>
Config file
{
"mcpServers": {
"hive-vault": {
"command": "uvx",
"args": [
"hive-vault"
],
"env": {
"VAULT_PATH": "<VAULT_PATH>",
"HIVE_OLLAMA_ENDPOINT": "<HIVE_OLLAMA_ENDPOINT>",
"OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>",
"HIVE_VAULT_SCOPES": "<HIVE_VAULT_SCOPES>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hive-vault <command>
Config file
{
"servers": {
"hive-vault": {
"type": "stdio",
"command": "uvx",
"args": [
"hive-vault"
],
"env": {
"VAULT_PATH": "<VAULT_PATH>",
"HIVE_OLLAMA_ENDPOINT": "<HIVE_OLLAMA_ENDPOINT>",
"OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>",
"HIVE_VAULT_SCOPES": "<HIVE_VAULT_SCOPES>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hive-vault <command>
Platform CLI
gemini mcp add -e VAULT_PATH=<VAULT_PATH> -e HIVE_OLLAMA_ENDPOINT=<HIVE_OLLAMA_ENDPOINT> -e OPENROUTER_API_KEY=<OPENROUTER_API_KEY> -e HIVE_VAULT_SCOPES=<HIVE_VAULT_SCOPES> hive-vault uvx hive-vaultReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hive-vault <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Hive Vault
How do I install Hive Vault in Claude Code?
Run claude mcp add hive-vault -e OPENROUTER_API_KEY=<OPENROUTER_API_KEY> -- uvx hive-vault. For a custom vault path and the other variables, use `claude mcp add --env VAULT_PATH=<VAULT_PATH> --env HIVE_OLLAMA_ENDPOINT=<HIVE_OLLAMA_ENDPOINT> --env OPENROUTER_API_KEY=<OPENROUTER_API_KEY> --env HIVE_VAULT_SCOPES=<HIVE_VAULT_SCOPES> --transport stdio hive-vault -- uvx hive-vault`.
What does Hive Vault do?
It connects an AI coding assistant to an Obsidian vault and serves notes on demand: 17 tools, 5 resources and 4 prompts. Context is not loaded wholesale, so project knowledge stays in the vault across sessions.
What does Hive Vault need to run?
Python 3.12+ and a directory of markdown files. git inside the vault is recommended: without it, writes still hit disk but skip the commit. delegate_task and capture_lesson need an OpenAI-compatible /v1 endpoint plus HIVE_WORKER_BASE_URL, HIVE_WORKER_API_KEY and HIVE_WORKER_MODEL.
