Obsidian-in-a-Vat

vault-mcp

Un servidor MCP de bóveda de conocimiento personal para Claude Desktop — captura pensamientos, conecta ideas y reflexiona sobre cómo cambia tu forma de pensar, todo mediante conversación natural.

📖  English   ·   📖  中文

Demostración

Una bóveda es más que una carpeta de notas: es un espejo de cómo piensas. vault_reflect convierte ese espejo en algo que puedes observar.

Instantánea · cómo se ve tu mente hoy	Deriva · cómo cambió durante el año
Burbujas de etiquetas + volumen mensual de capturas	Flujo apilado de velocidad de etiquetas a lo largo del tiempo

Por qué existe esto

La mayoría de las herramientas de toma de notas se quedan en el almacenamiento. vault-mcp está construido en torno a una visión de tres capas:

• L1 · Captura — guardado sin fricción desde cualquier conversación, con etiquetado automático y generación de slugs.
• L2 · Conexión — promueve capturas en bruto a notas estructuradas con wikilinks automáticos, construye un grafo de conocimiento, encuentra huérfanos y puentes.
• L3 · Reflexión — visualiza tu panorama de conocimiento, detecta deriva de intereses y descubre puntos ciegos con el tiempo.

El objetivo no es reemplazar a Obsidian. Es darle a Claude las manos y los ojos para trabajar dentro de tu bóveda.

Flujo de trabajo

flowchart LR
    Chat(["💬 Chat with Claude"]) -->|vault_capture| Cap[("📥 captures/")]
    Cap -->|vault_promote| Notes[("📝 notes/")]
    Notes -->|vault_analyze| Graph["🕸️ knowledge graph"]
    Notes -->|vault_topic| Topics[("🗺️ topics/ · MOC")]
    Cap -.->|vault_reflect| Mirror["🪞 snapshot · drift · blindspots"]
    Notes -.->|vault_reflect| Mirror
    Graph -.->|vault_reflect| Mirror

    classDef store fill:#eef2ff,stroke:#4c8bf5,color:#1e3a8a
    classDef view fill:#f0fdf4,stroke:#16a34a,color:#14532d
    classDef chat fill:#fef3c7,stroke:#d97706,color:#7c2d12
    class Cap,Notes,Topics store
    class Graph,Mirror view
    class Chat chat

Cada herramienta juega un rol distinto: vault_capture captura pensamientos en bruto, vault_promote los refina en notas, vault_analyze y vault_topic los entrelazan, y vault_reflect te permite dar un paso atrás y ver el panorama completo.

Inicio rápido (uvx — Recomendado)

La forma más ligera de ejecutar vault-mcp. Sin Docker, sin venv manual — solo uv y un cambio de configuración.

Paso 1. Instala uv (si no lo tienes):

curl -LsSf https://astral.sh/uv/install.sh | sh

Paso 2. Añádelo a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vault": {
      "command": "uvx",
      "args": ["obsidian-in-a-vat-mcp"],
      "env": {
        "VAULT_LOCAL_PATH": "/Users/yourname/my-vault"
      }
    }
  }
}

Reemplaza /Users/yourname/my-vault con la ruta absoluta a tu directorio de bóveda local.

Paso 3. Cierra y vuelve a abrir Claude Desktop por completo. Las herramientas de vault aparecerán automáticamente.

¿Aún no tienes una bóveda? Solo apunta VAULT_LOCAL_PATH a un directorio vacío. En el primer uso, pídele a Claude que "inicialice mi bóveda" — configurará automáticamente la estructura completa de directorios.

¿Ya tienes una bóveda de Obsidian? Apunta VAULT_LOCAL_PATH a tu bóveda existente y pídele a Claude que "inicialice mi bóveda". Escaneará tus notas, las clasificará (capturas vs. notas) y migrará todo al formato vault-mcp. Los originales se archivan de forma segura en _archive/.

{
  "mcpServers": {
    "vault": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/my-vault:/vault",
        "ghcr.io/oliverxuzy-ai/obsidian-in-a-vat:latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "vault": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/obsidian-in-a-vat",
        "vault-mcp"
      ],
      "env": {
        "VAULT_LOCAL_PATH": "/Users/yourname/my-vault"
      }
    }
  }
}

Herramientas

Las herramientas se agrupan según las tres capas de la visión.

📥 Captura y Lectura

🔗 Conexión

🪞 Reflexión

Extracción automática de etiquetas

Las etiquetas se extraen del texto de captura usando tres fuentes, en orden de prioridad:

1. tags.yaml — Etiquetas personalizadas y mapeos de sinónimos en la raíz de la bóveda
2. Notas existentes — Etiquetas recopiladas del frontmatter de los archivos existentes de la bóveda
3. Dominios predeterminados — Respaldo: ai, llm, productivity, writing, coding, design, business, learning, health, finance, philosophy, psychology

Ejemplo de tags.yaml en la raíz de tu bóveda:

tags:
  ai: [artificial intelligence, machine learning, ML, deep learning]
  coding: [programming, software, development, code]
  design: [UX, UI, user experience]

Desarrollo

# Run all tests
uv run pytest tests/ -v

# Build image locally
docker build -t vault-mcp .

# Test the container starts (Ctrl+C to stop)
echo '{}' | docker run -i --rm -v $(pwd)/example_vault:/vault vault-mcp

# Syntax check
python -m py_compile src/vault_mcp/server.py

# Interactive MCP Inspector
mcp dev src/vault_mcp/server.py

中文

个人知识库 MCP 服务器，适配 Claude Desktop —— 捕获想法、连接笔记、反思自己思维的变化，全部通过自然对话完成。

一图看懂

vault 不只是一个文件夹，而是你思维的一面镜子。vault_reflect 把这面镜子变成了你可以"看"的东西。

Snapshot · 当下你的思维长什么样	Drift · 这一年它如何变化
标签气泡 + 月度 capture 柱状图	堆叠式 tag velocity 流图

设计哲学

大多数笔记工具止步于"存储"。vault-mcp 围绕三层愿景设计：

• L1 · Capture — 任何对话中无摩擦地保存想法，自动打标签、生成 slug。
• L2 · Connect — 把原始 capture 提升为结构化笔记，自动插入 wikilinks，构建知识图谱，发现孤岛和桥接。
• L3 · Reflect — 可视化你的知识全景，呈现兴趣漂移，长期暴露盲区。

目标不是替代 Obsidian，而是让 Claude 拥有在你 vault 里"动手"和"看见"的能力。

工作流

flowchart LR
    Chat(["💬 与 Claude 对话"]) -->|vault_capture| Cap[("📥 captures/")]
    Cap -->|vault_promote| Notes[("📝 notes/")]
    Notes -->|vault_analyze| Graph["🕸️ 知识图谱"]
    Notes -->|vault_topic| Topics[("🗺️ topics/ · MOC")]
    Cap -.->|vault_reflect| Mirror["🪞 snapshot · drift · blindspots"]
    Notes -.->|vault_reflect| Mirror
    Graph -.->|vault_reflect| Mirror

    classDef store fill:#eef2ff,stroke:#4c8bf5,color:#1e3a8a
    classDef view fill:#f0fdf4,stroke:#16a34a,color:#14532d
    classDef chat fill:#fef3c7,stroke:#d97706,color:#7c2d12
    class Cap,Notes,Topics store
    class Graph,Mirror view
    class Chat chat

每个工具有清晰的分工：vault_capture 接住原始想法，vault_promote 把它们提炼成笔记，vault_analyze 和 vault_topic 把笔记编织起来，vault_reflect 让你后退一步看到全貌。

快速开始（uvx — 推荐）

最轻量的运行方式。不需要 Docker，不需要手动创建虚拟环境 — 只需安装 uv 即可。

第一步. 安装 uv（如果还没有）：

curl -LsSf https://astral.sh/uv/install.sh | sh

第二步. 添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "vault": {
      "command": "uvx",
      "args": ["obsidian-in-a-vat-mcp"],
      "env": {
        "VAULT_LOCAL_PATH": "/Users/yourname/my-vault"
      }
    }
  }
}

将 /Users/yourname/my-vault 替换为你本地 vault 目录的绝对路径。

第三步. 完全退出并重新打开 Claude Desktop，vault 工具会自动出现。

还没有 vault？ 将 VAULT_LOCAL_PATH 指向一个空目录即可。首次使用时让 Claude "初始化我的 vault" — 它会自动创建完整的目录结构。

已有 Obsidian vault？ 将 VAULT_LOCAL_PATH 指向你现有的 vault 目录，让 Claude "初始化我的 vault"。它会扫描你的笔记，自动分类（capture vs. note），并批量迁移为 vault-mcp 格式。原始文件安全归档到 _archive/。

{
  "mcpServers": {
    "vault": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/my-vault:/vault",
        "ghcr.io/oliverxuzy-ai/obsidian-in-a-vat:latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "vault": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/绝对路径/obsidian-in-a-vat",
        "vault-mcp"
      ],
      "env": {
        "VAULT_LOCAL_PATH": "/Users/yourname/my-vault"
      }
    }
  }
}

工具

按三层愿景分组。

📥 Capture & Read · 捕获与读取

🔗 Connect · 连接

🪞 Reflect · 反思

自动标签提取

标签从 capture 文本中提取，使用三个来源（按优先级排序）：

1. tags.yaml — vault 根目录的自定义标签和同义词映射
2. 已有笔记 — 收集已有 vault 文件 frontmatter 中的标签进行匹配
3. 默认领域 — 兜底列表：ai, llm, productivity, writing, coding, design, business, learning, health, finance, philosophy, psychology

tags.yaml 示例（放在 vault 根目录）：

tags:
  ai: [artificial intelligence, machine learning, ML, deep learning]
  coding: [programming, software, development, code]
  design: [UX, UI, user experience]

开发

# 运行所有测试
uv run pytest tests/ -v

# 本地构建镜像
docker build -t vault-mcp .

# 测试容器启动（Ctrl+C 停止）
echo '{}' | docker run -i --rm -v $(pwd)/example_vault:/vault vault-mcp

# 语法检查
python -m py_compile src/vault_mcp/server.py

# 使用 MCP Inspector 交互测试
mcp dev src/vault_mcp/server.py