内容
# obsidian-mcp
[](https://github.com/ykoellmann/obsidian-mcp/actions/workflows/ci.yml)
适用于 [Obsidian](https://obsidian.md) 知识库的MCP（模型上下文协议）服务器。直接连接Claude（或任何MCP客户端）到您的知识库 — 读取、写入、搜索、导航链接和管理笔记、画布和看板。
## 为什么选择obsidian-mcp？
官方Obsidian MCP插件需要Obsidian桌面应用程序运行，并且仅在同一台机器上有效。**obsidian-mcp是一个独立的服务器** — 不需要Obsidian应用程序。
预期的设置是在一台服务器或NAS上托管obsidian-mcp，您的知识库在那里持续同步（通过 [Syncthing](https://syncthing.net)、[git](https://github.com/denolehov/obsidian-git)、[rclone](https://rclone.org) 或 [Obsidian Sync](https://obsidian.md/sync)）。然后，Claude通过网络连接到该服务器，因此：
- **始终保持最新状态** — 服务器立即看到Obsidian应用程序写入的每个更改
- **从任何地方访问** — 从Claude Desktop、Claude Code或任何MCP客户端在任何机器上连接，无需本地存在知识库
- **多个客户端** — 几个Claude会话可以同时读取知识库；写入操作使用按文件锁定序列化
- **无应用程序依赖** — 服务器无头运行并自动启动（systemd、Docker等）
```
[Obsidian 应用] ──同步──► [服务器上的知识库] ◄──MCP── [任意机器上的Claude]
(手机/笔记本电脑) (NAS / VPS) (Claude Desktop / Code)
```
## 功能
- **读取和搜索** — 读取笔记、全文搜索（精确/正则/模糊）、渲染嵌入式转录、检查笔记大纲
- **写入** — 创建/覆盖笔记、修补章节、追加内容、更新前置信息、管理标签、移动笔记并自动重写wikilink
- **文件夹** — 列出、创建、删除、重命名文件夹；重命名会重写路径 기반的wikilink知识库范围
- **查询和图表** — 反向链接、损坏链接、孤立检测、BFS链接图表、知识库统计数据、任务集合跨知识库
- **类似Dataview的查询** — 按标签、状态、前置信息字段或内联字段过滤笔记（`key:: value`）
- **定期笔记** — 从模板读取/预览每日、每周、每月、季度、年度日记笔记
- **画布** — 读取、创建和修补Obsidian画布（`.canvas`）文件
- **看板** — 读取、创建和操作Obsidian看板（列和卡片）
- **附件** — 列出、读取（文本或base64）和添加二进制文件
- **模板** — 使用内置（`{{date}}`、`{{title}}`，...）和自定义变量渲染Obsidian模板
- **MCP资源** — 将知识库笔记、统计数据和标签作为MCP资源公开，直接注入上下文
## 安装
**通过uvx（无需克隆）：**
```bash
VAULT_PATH=/your/vault uvx obsidian-remote-mcp
```
**通过Docker（无需Python）：**
```bash
docker compose up -d # see docker-compose.yml
```
**从源码：**
```bash
git clone https://github.com/ykoellmann/obsidian-mcp.git
cd obsidian-mcp
uv sync
uv run obsidian-remote-mcp
```
## 配置
复制`.env.example`到`.env`并设置您的知识库路径：
```env
VAULT_PATH=/path/to/your/obsidian/vault
# 可选：
# READ_ONLY=true # 防止所有写入操作
# WRITE_PATHS=Notes/,Inbox/ # 限制写入操作到特定文件夹
# TRANSPORT=stdio # stdio（默认）或sse
```
## 与Claude Code一起使用
添加到您的MCP配置（例如`~/.claude/mcp.json`）：
```json
{
"mcpServers": {
"obsidian": {
"command": "uv",
"args": ["--directory", "/path/to/obsidian-mcp", "run", "obsidian-remote-mcp"],
"env": {
"VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
```
## 与Claude Desktop一起使用
添加到`claude_desktop_config.json`：
```json
{
"mcpServers": {
"obsidian": {
"command": "uv",
"args": ["--directory", "/path/to/obsidian-mcp", "run", "obsidian-remote-mcp"],
"env": {
"VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
```
## Docker
```bash
# 1. 复制并编辑环境变量
cp .env.example .env
# 2. 在.env中设置HOST_VAULT_PATH和API_KEY，然后：
docker compose up -d
```
`docker-compose.yml`从GHCR拉取预构建的镜像 — 无需克隆或构建。要在本地构建，请在compose文件中将`image:`替换为`build: .`。
## 远程设置（推荐）
在服务器上运行obsidian-mcp，并通过SSE传输远程连接。
**1. 生成API密钥：**
```bash
openssl rand -hex 32
```
**2. 配置服务器**（`docker-compose.yml`或`.env`）：
```env
VAULT_PATH=/data/vault
TRANSPORT=sse
API_KEY=your-generated-key
```
**3. 启动：**
```bash
docker compose up -d # 或：uv run obsidian-remote-mcp
```
**4. 从您的MCP客户端连接**（在网络上的任何位置）：
```json
{
"mcpServers": {
"obsidian": {
"type": "sse",
"url": "https://your-server/sse",
"headers": {
"Authorization": "Bearer your-generated-key"
}
}
}
}
```
> **安全：** 在通过互联网公开时，请始终在前面添加一个TLS终止反向代理（例如 [Caddy](https://caddyserver.com)）。`API_KEY`对于stdio传输（仅限本地使用）不是必需的。
使用Syncthing、git+cron、rclone或Obsidian Sync在服务器上保持知识库同步 — obsidian-mcp通过文件监视器自动拾取更改。
## 知识库约定（自定义）
在您的知识库根目录中创建 `_AI_INSTRUCTIONS.md` 以教导AI您的特定知识库组织方式：
```markdown
## 结构
- `Notes/` — 常绿笔记和概念
- `Projects/` — 活动和存档项目（标签：#project/active, #project/done）
- `Journal/` — 每日笔记（YYYY-MM-DD.md）
## 前置信息模式
- 状态：active | done | inbox
- 标签：嵌套使用/（例如#concept/programming）
## 约定
- 仅使用词干链接，从不使用完整路径
- 每个笔记需要在前置信息中有一个创建时间
```
服务器在启动时加载此文件，并将其作为系统指令发送给AI。如果没有它，则使用内置的通用Obsidian语法指导。 `_AI_INSTRUCTIONS.md` 是特定于知识库的正确位置 — 文件夹布局、标签模式、命名约定和任何工作流规则。
## 工具参考
| 类别 | 工具 |
|---|---|
| **读取** | `list_notes`、`read_note`、`search_notes`、`render_note`、`get_note_outline` |
| **写入** | `write_note`、`patch_note`、`delete_note`、`append_to_note`、`patch_frontmatter`、`manage_tags`、`move_note` |
| **文件夹** | `list_folder`、`create_folder`、`delete_folder`、`rename_folder` |
| **查询** | `query_notes`、`get_backlinks`、`get_broken_links`、`get_orphans`、`get_link_graph`、`get_vault_stats`、`get_tasks`、`resolve_alias` |
| **标签** | `get_notes_by_tag`、`get_tag_tree`、`list_all_tags` |
| **定期** | `get_daily_note`、`get_periodic_note` |
| **画布** | `list_canvases`、`read_canvas`、`write_canvas`、`patch_canvas` |
| **看板** | `read_kanban`、`create_kanban_board`、`add_kanban_card`、`move_kanban_card`、`delete_kanban_card` |
| **附件** | `list_attachments`、`read_attachment`、`add_attachment` |
| **模板** | `list_templates`、`create_from_template` |
完整的参数文档嵌入在服务器中，并自动显示给连接的AI客户端。
## 架构
```
src/obsidian_mcp/
├── config.py # 基于环境的配置（VAULT_PATH, READ_ONLY, WRITE_PATHS）
├── server.py # FastMCP入口点，工具和资源注册
├── domain/
│ ├── models.py # 笔记数据类（前置信息，标签，wikilink，任务等）
│ ├── parser.py # Markdown解析器（YAML前置信息，wikilink，块引用等）
│ └── index.py # 知识库索引 — 别名解析，反向链接，标签树，BFS
├── storage/
│ ├── filesystem.py # 原子写入（临时 + os.replace），路径验证
│ ├── locking.py # 按文件锁定以防止并发写入冲突
│ └── watcher.py # 基于监视器的知识库更改检测（轮询回退）
└── tools/
├── read.py # read_note, search_notes, render_note, get_note_outline
├── write.py # write_note, patch_note, move_note, manage_tags, …
├── query.py # 图形工具，任务聚合，定期笔记，query_notes
├── folders.py # 文件夹管理
├── canvas.py # Obsidian画布（.canvas JSON）工具
├── kanban.py # Obsidian看板插件工具
├── attachments.py # 二进制和文本附件处理
└── templates.py # 模板渲染，变量替换
```
## 开发
```bash
uv run pytest # 运行测试（238个测试）
uv run ruff check src/ tests/ # 校验
```
## 许可证
MIT
