内容
# obsidian-local-mcp
本地磁盘的特定目录作为 **Obsidian Vault** 的MCP服务器。
Claude（桌面版/代码版）可以在Vault内**创建、读取、修改**笔记，并**读取和创建**文件夹。Claude创建的所有新笔记都将默认赋予按固定顺序排列的Obsidian属性（YAML frontmatter）：
```yaml
---
title:
aliases:
tags:
author:
date:
source:
type:
Service URL:
---
```
Vault位置和默认作者可以在**本地Web设置页面（GUI）**中更改。
## 组件
| 项目 | 描述 |
| --- | --- |
| MCP服务器 (`dist/index.js`) | 提供7种工具（见下） |
| 设置页面 (`npm run settings`) | localhost网页UI — Vault文件夹选择（本地对话框）+ 默认作者 |
| 技能 (`skills/obsidian-vault`) | 包含Vault联动工作规则的Claude技能 |
### MCP工具
- `create_note` — 创建新笔记（自动赋予YAML属性）
- `read_note` — 读取笔记原文/frontmatter/正文
- `update_note` — 修改正文（追加/插入/替换正文）·frontmatter部分
- `list_directory` — 文件夹列表（递归选项）
- `create_directory` — 创建文件夹
- `search_notes` — 文件名/正文/标签搜索
- `get_vault_info` — Vault路径·默认作者·笔记数确认
## 安装
```bash
npm install
npm run build
```
## 1) 指定Vault（GUI）
```bash
npm run settings
```
浏览器中打开设置页面。点击**“选择文件夹…”**，弹出macOS文件夹对话框，选择Vault文件夹（可直接输入），输入默认`author`后点击**保存**。
设置存储在以下位置，运行的MCP服务器从下一次工具调用开始生效：
```
~/Library/Application Support/obsidian-local-mcp/config.json
```
> 注意：如果没有设置文件，环境变量`OBSIDIAN_VAULT_PATH`将作为备用方案使用。
## 2) 注册到Claude
### Claude Code（命令行）
```bash
claude mcp add obsidian -- node /ABSOLUTE/PATH/TO/obsidian-local-mcp/dist/index.js
```
或者在项目根目录下参考`examples/mcp.json`的内容创建`.mcp.json`文件。
将技能复制到以下位置：
```bash
# 全局使用
cp -r skills/obsidian-vault ~/.claude/skills/
# 或者仅在特定项目中使用
cp -r skills/obsidian-vault /your/project/.claude/skills/
```
### Claude Desktop
在`claude_desktop_config.json`中添加以下内容（参考`examples/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/obsidian-local-mcp/dist/index.js"]
}
}
}
```
设置文件位置：`~/Library/Application Support/Claude/claude_desktop_config.json`.
修改后重启Claude Desktop。在Claude Desktop的Skills（Capabilities）设置中添加/启用`skills/obsidian-vault`文件夹。
## 工作方式 / 安全性
- 所有路径**仅允许相对于Vault根目录的相对路径**。绝对路径和`..`跳转均被拒绝，以防止访问Vault外部文件。
- frontmatter始终按固定的8个键顺序序列化（`aliases`/`tags`为列表，`date`为Obsidian日期格式，不带引号）。
- 以点（`.`）开头的文件夹和文件，如`.obsidian`和`.trash`，在列表和搜索中被忽略。
## 验证（MCP Inspector）
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
在Inspector中按`get_vault_info` → `create_note` → `read_note` → `list_directory`顺序调用，以验证功能。
