内容
# @istrejo/obsidian-mcp
> 连接Claude（桌面版和代码版）到Obsidian笔记库的MCP服务器，通过直接文件系统访问。
[](https://www.npmjs.com/package/@istrejo/obsidian-mcp)
[](https://www.npmjs.com/package/@istrejo/obsidian-mcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/istrejo/obsidian-mcp/actions/workflows/ci.yml)
## 功能特点
- **13种强大的工具**，用于阅读、编写、搜索和组织笔记
- **直接文件系统访问** - 无需Obsidian插件，即使Obsidian关闭也能正常工作
- **设计安全**：路径遍历防护、只读模式、删除前自动备份
- **适用于Claude Desktop和Claude Code**，通过stdio传输
- **零配置**，只需指定笔记库路径
## 要求
- Node.js >= 20
- 已存在的Obsidian笔记库
## 安装和设置
### 对于Claude Desktop
1. 打开Claude Desktop配置文件：
- **macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows：** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux：** `~/.config/Claude/claude_desktop_config.json`
2. 添加以下配置：
```json
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "@istrejo/obsidian-mcp"],
"env": {
"OBSIDIAN_VAULT_PATH": "/绝对路径/到/你的/笔记库"
}
}
}
}
```
3. 重启Claude Desktop。
### 对于Claude Code
在终端中运行此命令：
```bash
claude mcp add obsidian -e OBSIDIAN_VAULT_PATH=/绝对路径/到/你的/笔记库 -- npx -y @istrejo/obsidian-mcp
```
或手动编辑 `~/.claude/mcp.json`:
```json
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "@istrejo/obsidian-mcp"],
"env": {
"OBSIDIAN_VAULT_PATH": "/绝对路径/到/你的/笔记库"
}
}
}
}
```
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `OBSIDIAN_VAULT_PATH` | ✅ 是 | — | Obsidian笔记库目录的绝对路径 |
| `OBSIDIAN_READ_ONLY` | 否 | `false` | 设置为 `true` 以禁用所有写入/删除操作 |
| `OBSIDIAN_MAX_FILE_SIZE` | 否 | `10485760` (10 MB) | 读取/写入操作的最大文件大小（字节） |
| `OBSIDIAN_BACKUP_ENABLED` | 否 | `true` | 是否在删除笔记前创建备份 |
| `OBSIDIAN_LOG_LEVEL` | 否 | `info` | 日志详细程度：`debug`、`info`、`warn` 或 `error` |
## 可用工具
| 工具 | 描述 | 示例提示 |
|------|-------------|----------------|
| `read_note` | 读取笔记的全文和前置信息 | *"读取我的Projects/my-project笔记"* |
| `list_notes` | 列出所有笔记，可选按文件夹过滤 | *"列出Resources文件夹中的所有笔记"* |
| `list_recent` | 显示最近修改的笔记 | *"我的5个最近编辑的笔记是什么？"* |
| `search_content` | 跨所有笔记进行全文搜索 | *"在我的所有笔记中搜索'microservices'"* |
| `search_by_tags` | 按标签查找笔记 | *"查找所有标记为#project/active的笔记"* |
| `create_note` | 创建新的笔记，可选前置信息 | *"在Daily文件夹中为今天创建每日笔记"* |
| `update_note` | 追加、prepend或替换笔记内容 | *"在我的会议笔记中添加摘要部分"* |
| `manage_frontmatter` | 读取或更新YAML前置信息 | *"在我的任务笔记中将状态字段设置为'done'"* |
| `manage_folders` | 创建、列出或删除文件夹 | *"创建Archive/2024文件夹"* |
| `move_note` | 移动或重命名笔记，更新反向链接 | *"将Projects/old-name重命名为Projects/new-name"* |
| `delete_note` | 删除笔记（自动备份） | *"删除Drafts/scratch草稿笔记"* |
| `get_backlinks` | 查找链接到给定笔记的所有笔记 | *"哪些笔记链接到Resources/book？"* |
| `get_graph` | 获取完整的wikilink连接图 | *"从索引开始，显示我的笔记如何连接"* |
## 安全
- **路径遍历防护：** 所有路径都经过验证，以保持在笔记库边界内。诸如`../../../etc/passwd`的请求会被直接拒绝。
- **只读模式：** 设置`OBSIDIAN_READ_ONLY=true`以禁用所有写入和删除操作。对于给予Claude只读访问权限非常有用。
- **自动备份：** 在删除任何笔记之前，会在笔记库内的`.obsidian-mcp-trash/{timestamp}/`中保存一份副本。设置`OBSIDIAN_BACKUP_ENABLED=false`以禁用。
- **文件大小限制：** 大于`OBSIDIAN_MAX_FILE_SIZE`字节的文件被拒绝，以防止运行失控的读取/写入。
- **结构化日志：** 所有破坏性操作（创建、更新、删除、移动）都会记录到stderr，并带有时间戳。
## 使用示例
```
"在Daily文件夹中创建今天的新每日笔记，标签为：daily, journal"
"在我的所有笔记中搜索'microservices'并总结我写的内容"
"查找所有标记为#project/active且最近30天未修改的笔记"
"将Inbox文件夹中的所有笔记移动到相应的项目子文件夹"
"显示链接回我的'index'笔记的所有内容"
"从我的'architecture'笔记开始，构建一个知识图，深度为3层"
```
## 开发
```bash
git clone https://github.com/istrejo/obsidian-mcp.git
cd obsidian-mcp
npm install
# 以开发模式运行（使用tsx，无需构建）
OBSIDIAN_VAULT_PATH=/路径/到/你的/笔记库 npm run dev
# 类型检查
npm run typecheck
# 校验
npm run lint
# 运行测试
npm test
# 构建生产版本
npm run build
```
## 贡献
欢迎提交PR。请遵循[Conventional Commits](https://www.conventionalcommits.org/)：
- `feat:` 新功能
- `fix:` 错误修复
- `docs:` 文档更新
- `chore:` 构建/工具更新
- `test:` 测试更新
- `refactor:` 重构
## 许可证
MIT © [José Alejandro Trejo Rivera](https://github.com/istrejo)
