convez.ai
MCP ServerIntegração & APIsIntermediário
videnovnebojsa

Vault MCP - Servidor MCP para Obsidian

videnovnebojsa/vault-mcp

Acesso sempre-on ao Obsidian via MCP, sem plugin, com busca semântica

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que oferece acesso direto e sempre ativo ao seu vault Obsidian sem exigir plugin ou ter o app aberto. Implementa busca híbrida (palavra-chave + semântica), captura de notas com classificação automática e operações de arquivo conscientes de backlinks, permitindo que Claude e outros agentes gerenciem seu conhecimento diretamente do sistema de arquivos.

Instalação

$npx convez-ai videnovnebojsa/vault-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 4 dias
Versão
v0.2.2
Issues abertas
6
Contribuidores
1

Casos de uso

  • Buscar e recuperar notas por tópico com busca híbrida (palavra-chave + semântica)
  • Capturar e organizar ideias automaticamente na pasta correta com classificação
  • Gerenciar ligações internas (wikilinks) ao mover, renomear ou deletar notas
  • Triage automático de inbox com movimentação em lote baseada em confiança
  • Criar e acessar notas diárias, semanais e mensais sob demanda

Veredito

Solução robusta e bem arquitetada para integração de Obsidian com Claude. Destaca-se pela busca híbrida inteligente e operações de arquivo conscientes de backlinks, eliminando a necessidade de plugins. Ideal para quem quer automação séria de gestão de conhecimento.

README

A tradução para o português deste README ainda está na fila.

vault-mcp

CI License: MIT Bun ≥ 1.3

MCP server that gives your agent direct, always-on access to your Obsidian vault - no plugin, no Obsidian process required.

Ask Claude (or any other agent) to find everything you've written about a topic, draft a note in the right folder, or triage your inbox - without ever opening Obsidian.

Why vault-mcp?

Works whether Obsidian is open or not - reads your vault straight from the filesystem, so your agent isn't blocked when the app is closed.

One vault, many AI tools at once - it runs as an always-on server, so Claude Code and Claude Desktop can talk to the same vault at the same time, sharing one live index.

Finds what you mean, not just what you typed - hybrid search blends keyword ranking and semantic embeddings. Exact phrases surface when precision matters; conceptual queries work when it doesn't.

Demo

vault-mcp demo

What you can do

Read & write notes

  • Ask for a note, a section of one, or a note plus everything it links to - in a single call
  • Move or rename a note and every [[wikilink]] pointing to it updates automatically
  • Delete safely - soft-delete sends notes to .trash/ instead of destroying them
  • Change one note or batch dozens of moves, deletes, and frontmatter edits in one go

Find & connect

  • Search your whole vault by keyword, by meaning, or both at once - with tag, type, and date filters
  • Surface notes that should be linked but aren't, so related ideas stop drifting apart

Capture & triage

  • Drop in free-form text and have it classified and filed in the right folder for you
  • Auto-triage your inbox: move everything above a confidence threshold to where it belongs
  • Open or create today's daily, this week's weekly, or this month's monthly note on demand

Runs as a service

  • Name and switch between multiple vaults from one server instance
  • Connect Claude Desktop through the bundled stdio bridge
  • Automatic SQLite index backups with configurable retention
  • OpenTelemetry spans per tool call and webhook alerts, plus /health and /ready probes

Quick Start

Option 1 - Quick install (no Bun required)

Downloads the pre-built binary for your platform, walks you through configuration, and optionally installs a background service.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/videnovnebojsa/vault-mcp/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/videnovnebojsa/vault-mcp/main/install.ps1 | iex

To reconfigure later (vault path, port, etc.):

bash install.sh --configure    # macOS / Linux
.\install.ps1 -Configure       # Windows

Option 2 - Developer install (build from source)

Requires Bun 1.3+.

git clone https://github.com/videnovnebojsa/vault-mcp
cd vault-mcp
bun install
bun run setup

bun run setup builds the binary, walks you through configuration, and installs a background service that starts at login - launchd on macOS, systemd on Linux, Task Scheduler on Windows.

Connect Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "vault": { "type": "http", "url": "http://127.0.0.1:3782/mcp" }
  }
}

Connect Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "vault": {
      "command": "/path/to/vault-mcp",
      "args": ["bridge"],
      "env": { "VAULT_MCP_URL": "http://127.0.0.1:3782/mcp" }
    }
  }
}

Replace /path/to/vault-mcp with the actual binary path — typically ~/.local/bin/vault-mcp after a quick install or /usr/local/bin/vault-mcp after a manual install. The vault-mcp server must be running (the background service installed by the setup script handles this automatically).

The claude_desktop_config.json location varies by platform and build — see docs/clients.md. Windows users on the Microsoft Store build of Claude Desktop have it under %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\..., not %APPDATA%\Claude; install.ps1 detects and prints the right path.

Verify

curl http://localhost:3782/health
# {"status":"ok","uptimeSeconds":12,...}

/health always returns 200; /ready returns 503 until the vault index finishes its initial sync.

Common workflows

Once connected, just talk to your agent in plain language. Try:

  • "Find my notes on productivity systems" → hybrid search across your whole vault
  • "File this meeting summary" → capture pipeline classifies it and routes it to the right folder
  • "What notes should I connect to this one?" → semantic connection finder surfaces related notes
  • "Archive these three project notes" → batch move, with every [[wikilink]] rewritten automatically

See docs/prompts.md for the full prompt cheat-sheet.

Configuration

All settings live in ~/.config/vault-mcp/.env. The setup script writes this file with your answers and leaves every optional variable commented out with its default; for a manual install, start from .env.example.

To change settings interactively after installation:

bun run configure

This opens a section menu, validates each setting, shows a diff of what will change, and optionally restarts the service. Jump straight to a section with --section <id>:

bun run configure -- --section embeddings

Custom folder structure? vault-mcp defaults to a numbered Zettelkasten-style layout. Run bun run configure -- --section vault-folders to remap the capture pipeline to your own folder names.

To edit the file by hand instead, open ~/.config/vault-mcp/.env and restart the service:

PlatformCommand
macOSlaunchctl kickstart -k gui/$UID/com.vault-mcp
Linuxsystemctl --user restart vault-mcp
Windowsschtasks /End /TN vault-mcp && schtasks /Run /TN vault-mcp

Development

bun run test                      # run test suite
bun run build                     # compile TypeScript → dist/
bun run lint                      # biome check

Binary build scripts (require Bun):

bun run build:bun                 # standalone executable → dist-bin/
bun run scripts/smoke-test.ts     # smoke test the built binary against a real vault

Documentation

TopicLink
Installation options (manual, service)docs/installation.md
Connecting MCP clientsdocs/clients.md
Example prompts cheat-sheetdocs/prompts.md
How hybrid search worksdocs/semantic-search.md
Full configuration referencedocs/configuration.md
Full tool referencedocs/tools.md
Feature roadmap & statusdocs/roadmap.md

Contributing

TopicLink
Internal module map & data flowdocs/contributing/architecture.md
Architectural rules & patternsdocs/contributing/design-standards.md
Tooling, lint, test, CI standardsdocs/contributing/typescript-standards.md

License

MIT

Ver o original no GitHub

Bom para

Relacionados