Obsidian MCP Server

让 AI 客户端搜索你的 Obsidian 笔记。

Obsidian MCP Server 是一个最小可用的 MCP (Model Context Protocol) 服务器，让 Claude Desktop、Cursor 等 AI 客户端直接搜索你本地 Obsidian vault 中的 Markdown 笔记。

启发自 obsidian-llm-wiki 和 Karpathy 的 LLM Wiki 概念。

架构

flowchart LR
    A[Claude Desktop] -->|MCP stdio| B[Obsidian MCP Server]
    B -->|pathlib + re| C[Obsidian Vault<br/>*.md files]

只做一件事：暴露 search_vault 工具，在 vault 中全文搜索 .md 文件，返回匹配结果。

安装

pip install mcp

配置

1. 设置环境变量

export OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault
# 或 Windows PowerShell:
# $env:OBSIDIAN_VAULT_PATH = "C:\Users\You\Documents\Obsidian\MyVault"

2. 配置 Claude Desktop

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

3. 手动运行测试

cd obsidian-mcp-server
OBSIDIAN_VAULT_PATH=/path/to/vault python server.py

使用

配置好后，在 Claude Desktop 中直接问：

"Search my vault for meeting notes about project Alpha"

"在我笔记里找关于机器学习的内容"

AI 会自动调用 search_vault 工具，返回匹配的文件名和内容片段。

API

search_vault

参数	类型	默认值	说明
query	string	(必填)	搜索关键词
max_results	integer	10	最大返回结果数

限制 & 未来计划

当前限制：

• 仅支持简单的关键词搜索（大小写不敏感）
• 不支持语义搜索（不调 embedding）
• 不解析 Obsidian 特有语法（frontmatter / wiki-links / callouts）
• 跳过大文件时无提示

计划中的功能：

• [ ] read_note — 读取单篇笔记全文
• [ ] get_backlinks — 解析 [[wiki-links]] 反向链接
• [ ] 可选 embedding 语义搜索
• [ ] watch 模式自动文件变更监听

License

MIT

---

Obsidian MCP Server

Let AI clients search your Obsidian notes.

Obsidian MCP Server is a minimal MCP (Model Context Protocol) server that lets AI clients like Claude Desktop and Cursor search your local Obsidian vault.

Inspired by obsidian-llm-wiki and Karpathy's LLM Wiki concept.

Architecture

flowchart LR
    A[Claude Desktop] -->|MCP stdio| B[Obsidian MCP Server]
    B -->|pathlib + re| C[Obsidian Vault<br/>*.md files]

Does one thing: exposes a search_vault tool that full-text searches .md files in your vault.

Installation

pip install mcp

Configuration

1. Set environment variable

export OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault

2. Configure Claude Desktop

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

3. Test manually

cd obsidian-mcp-server
OBSIDIAN_VAULT_PATH=/path/to/vault python server.py

Usage

Once configured, ask in Claude Desktop:

"Search my vault for meeting notes about project Alpha"

The AI will call search_vault and return matching filenames with content snippets.

API

search_vault

Parameter	Type	Default	Description
query	string	required	Search term or phrase
max_results	integer	10	Maximum number of results

Limitations & Roadmap

Current limitations:

• Keyword search only (case-insensitive)
• No semantic search (no embedding)
• Does not parse Obsidian syntax (frontmatter / wiki-links / callouts)

Planned features:

• [ ] read_note — read a single note's full content
• [ ] get_backlinks — parse [[wiki-links]] backlinks
• [ ] Optional embedding-based semantic search
• [ ] Watch mode for automatic file change detection

License

MIT