# Obsidian MCP Server

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

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

> 启发自 [obsidian-llm-wiki](https://github.com/green-dalii/obsidian-llm-wiki) 和 [Karpathy 的 LLM Wiki 概念](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)。

## 架构

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

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

## 安装

```bash
pip install mcp
```

## 配置

### 1. 设置环境变量

```bash
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 的配置文件中添加：

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

### 3. 手动运行测试

```bash
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)](https://modelcontextprotocol.io) server that lets AI clients like Claude Desktop and Cursor search your local Obsidian vault.

> Inspired by [obsidian-llm-wiki](https://github.com/green-dalii/obsidian-llm-wiki) and [Karpathy's LLM Wiki concept](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).

## Architecture

```mermaid
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

```bash
pip install mcp
```

## Configuration

### 1. Set environment variable

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

### 2. Configure Claude Desktop

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

### 3. Test manually

```bash
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