Obsidian-in-a-Vat

A personal knowledge vault MCP server for Claude Desktop —capturethoughts,connectideas, andreflecton how your thinking is changing, all through natural conversation.

A vault is more than a folder of notes — it's a mirror of how you think.vault_reflectturns that mirror into something you can look at.

https://github.com/user-attachments/assets/0ef205a4-0ffc-4a24-a92a-b4acf66377fe

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

Each tool plays a distinct role:vault_capturelands raw thoughts,vault_promoterefines them into notes,vault_analyze&vault_topicweave them together, andvault_reflectlets you step back and see the whole picture.

The lightest way to run vault-mcp. No Docker, no manual venv — justuvand one config change.

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

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

Replace/Users/yourname/my-vaultwith the absolute path to your local vault directory.

Step 3.Fully quit and reopen Claude Desktop. Thevaulttools will appear automatically.

Don't have a vault yet?Just pointVAULT_LOCAL_PATHto an empty directory. On first use, ask Claude to"initialize my vault"— it will set up the full directory structure automatically.

Already have an Obsidian vault?PointVAULT_LOCAL_PATHto your existing vault and ask Claude to"initialize my vault". It will scan your notes, classify them (captures vs. notes), and migrate everything into the vault-mcp format. Originals are safely archived under_archive/.

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

RequiresDocker Desktoprunning in the background.

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

Switch back to the published version by changingcommandto"uvx"andargsto["obsidian-in-a-vat-mcp"].

Tools are grouped by the three layers of the vision.

Tags are extracted from capture text using three sources, in priority order:
- tags.yaml— Custom tags and synonym mappings at the vault root
- Existing notes— Tags collected from existing vault files' frontmatter
- Default domains— Fallback:ai,llm,productivity,writing,coding,design,business,learning,health,finance,philosophy,psychology

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

# 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把这面镜子变成了你可以"看"的东西。

大多数笔记工具止步于"存储"。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让你后退一步看到全貌。

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

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

{ "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" ] } } }

更新到最新版：docker pull 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" } } } }

切回已发布版本：将command改为"uvx"，args改为["obsidian-in-a-vat-mcp"]。
- tags.yaml— vault 根目录的自定义标签和同义词映射
- 已有笔记— 收集已有 vault 文件 frontmatter 中的标签进行匹配
- 默认领域— 兜底列表：ai,llm,productivity,writing,coding,design,business,learning,health,finance,philosophy,psychology

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

Manage Obsidian vaults with knowledge graph operations and AI-powered features.

Create notes, search, & think with your Fabric AI workspace

Connect AI assistants to your Aiqbee knowledge graph via MCP.

Portable, cloud-hosted AI memory you own - structured memories, tasks, goals, and notes that work across Claude, ChatGPT, Gemini, and any MCP client.

Persistent memory for AI agents. Single SQLite file, 192 MCP tools. FTS5 search, knowledge graph, session handoffs, write gate. No server, no API keys, no LLM calls.

Turn Claude Desktop conversations into visual mind maps via MCP. Highlights blockers to surface where you're stuck. No extra API key needed.

A Markdown-based second brain with a hosted MCP server. Your AI reads, searches, creates, and links your notes. Free tier included.

Connect your Limitless Pendant data to Claude and other LLMs using the Limitless API.

🏠 🍎 🪟 🐧 - A self-contained Memory server with single-binary architecture (embedded DB & models, no dependencies). Provides persistent semantic and graph-based memory for AI agents.

A private, local research "second brain" for Claude — cited answers from your own library (it won't invent what it can't find), persistent project memory, daily briefs, a live meeting assistant, and 34 specialist agents. Runs entirely on your machine.