内容
# Obsidian MCP 服务器
> **直接将 Claude Desktop 连接到您的 Obsidian 知识库。**
> 请求 Claude 读取、编写、搜索和组织您的笔记 - 所有操作都可以在单个对话中完成。
---
## 视频教程
**刚接触 MCP 或不确定从哪里开始？**
在 YouTube 上观看完整的逐步教程：
**[观看教程 → youtube.com/@dojicreates](https://www.youtube.com/@dojicreates/videos)**
---
## PDF 安装指南
想要一份可打印的、带截图的离线参考指南吗？
**[获取 PDF 指南 → dojicreates.com](https://dojicreates.com/)**
本指南涵盖了安装、配置以及您可以立即复制并使用的示例提示。
---
## 功能介绍
MCP（模型上下文协议）是一种开放标准，允许 AI 助手调用外部工具。
该服务器实现了该标准，并将您的 Obsidian 知识库公开为 Claude 可以使用的工具集。
```
Claude Desktop ←──── MCP (stdio) ────→ server.py ←── file I/O ──→ Obsidian 知识库
```
- **100% 本地运行** - 无需云服务、无需 Obsidian 插件、无需 API 密钥
- Claude 只能访问您知识库内的文件 - 机器上的其他文件均不可访问
- 支持 **Windows 和 macOS**
---
## 目录结构
```
mcp/
├── .venv/ ← 隔离的 Python 环境（安装时创建）
├── server.py ← MCP 服务器
├── config.json ← 您的知识库路径（此处）（不会提交到 git）
├── requirements.txt ← Python 依赖项
├── start_server.bat ← 可选：手动在 Windows 上运行服务器
└── README.md ← 本文件
```
---
## 先决条件
- [Python 3.10+](https://www.python.org/downloads/) 已安装
- [Claude Desktop](https://claude.ai/download) 已安装
- 机器上有 [Obsidian](https://obsidian.md/) 知识库
---
## 设置（5 分钟）
### 步骤 1 - 下载本项目
点击此页面上的 **代码 → 下载 ZIP**，并在机器上的任意位置解压，
或使用 git 克隆：
```bash
git clone https://github.com/YOUR_USERNAME/obsidian-mcp-server.git
cd obsidian-mcp-server
```
---
### 步骤 2 - 创建 Python 虚拟环境
在项目文件夹内打开终端并运行：
**Windows（PowerShell 或命令提示符）：**
```powershell
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```
**macOS / Linux：**
```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```
---
### 步骤 3 - 设置知识库路径
打开 `config.json` 并将占位符替换为 Obsidian 知识库的实际路径：
```json
{
"vault_path": "C:/Users/YOUR_USERNAME/Documents/YourVaultName"
}
```
**如何在 Obsidian 中找到知识库路径：**
`设置 → 文件和链接 → 知识库路径`（显示在该部分的顶部）。
> 在 Windows 上使用正斜杠 `/`，或使用反斜杠 `\` 进行转义。
> `config.json` 位于 `.gitignore` 中 - 它不会被推送到 GitHub，从而保护您的个人路径。
---
### 步骤 4 - 连接 Claude Desktop
Claude Desktop 从配置文件中读取其 MCP 服务器列表。
**查找配置文件：**
| 操作系统 | 位置 |
|---------|----------|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
在任意文本编辑器中打开该文件。如果它不存在，请创建它。
**添加此块**，将路径替换为项目文件夹的实际位置：
**Windows 示例：**
```json
{
"mcpServers": {
"obsidian": {
"command": "C:\\Users\\YOUR_USERNAME\\path\\to\\mcp\\.venv\\Scripts\\python.exe",
"args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\mcp\\server.py"],
"env": {}
}
}
}
```
**macOS 示例：**
```json
{
"mcpServers": {
"obsidian": {
"command": "/Users/YOUR_USERNAME/path/to/mcp/.venv/bin/python",
"args": ["/Users/YOUR_USERNAME/path/to/mcp/server.py"],
"env": {}
}
}
}
```
> 如果文件中已经有其他 MCP 服务器，请在现有的 `"mcpServers"` 对象内添加 `"obsidian": { ... }` 块。不要创建第二个 `"mcpServers"` 键。
**保存文件，然后完全退出并重新打开 Claude Desktop。**
在 Windows 上：右键单击系统托盘图标 → 退出，然后重新启动。
---
### 步骤 5 - 验证其是否有效
在 Claude Desktop 中启动新对话并输入：
> "列出所有我的笔记"
或
> "显示知识库结构"
您应该在聊天界面中看到一个工具图标 - 这意味着 Claude 已连接到您的知识库。
---
## 可用工具
| 工具 | 功能 |
|------|-------------|
| `read_note(path)` | 读取笔记的完整内容 |
| `write_note(path, content)` | 创建或覆盖笔记 |
| `append_to_note(path, content)` | 在笔记末尾添加文本 |
| `delete_note(path)` | 永久删除笔记 |
| `list_notes(folder?)` | 列出所有 `.md` 文件（可选在文件夹内） |
| `search_notes(query, folder?, case_sensitive?)` | 笔记的全文/正则搜索 |
| `get_vault_structure(max_depth?)` | 文件夹和文件的树形视图 |
| `move_note(source, destination)` | 移动或重命名笔记 |
| `get_or_create_daily_note(date?)` | 获取今日的日常笔记；如果不存在，则从模板创建 |
所有路径均为**相对于知识库根目录**。
示例：`"Ideas/Project Alpha.md"` - 而不是完整系统路径。
---
## 示例提示
```
"在我的笔记中搜索与机器学习相关的任何内容"
"在我的 Work 文件夹中创建一个名为 Meeting Notes 的笔记，包含今天的行动项"
"在我的日常笔记中添加一个任务：查看项目提案"
"显示我的 Projects 文件夹中的所有内容"
"将我的草稿论文从 Drafts/Essay.md 移动到 Published/Essay.md"
```
---
## 更改知识库路径
编辑 `config.json` 并更新 `vault_path`。保存后重启 Claude Desktop。
或者，您可以跳过 `config.json` 并设置环境变量：
```
OBSIDIAN_VAULT_PATH=C:/Users/YOUR_USERNAME/Documents/YourVaultName
```
环境变量优先于 `config.json`。
---
## 故障排除
### Claude 未显示工具图标 / 服务器未找到
1. 再次检查 `claude_desktop_config.json` 中的路径 - 在 Windows 上使用双反斜杠 `\\`。
2. 确保您完全退出 Claude Desktop（不仅仅是关闭窗口）并重新启动。
3. 通过在终端中打开并运行来手动测试服务器：
```
# Windows
.venv\Scripts\python.exe server.py
# macOS / Linux
.venv/bin/python server.py
```
它应该打印出内容并等待 - 这意味着它正在工作。按 `Ctrl+C` 停止。
### "知识库路径未设置" 错误
`config.json` 丢失或 `vault_path` 为空。确保 `config.json` 与 `server.py` 位于同一文件夹中，并包含有效路径。
### "路径超出知识库根目录" 错误
您传递了绝对路径而不是相对于知识库的路径。
使用 `"Ideas/note.md"` 而不是 `"C:/Users/.../Ideas/note.md"`。
### 笔记未显示
确保 `vault_path` 指向知识库的**根目录** - 包含 `.obsidian` 隐藏文件夹的文件夹，而不是其中的子文件夹。
### 重新安装依赖项
如果您删除了 `.venv` 或将项目移动到新文件夹，请再次运行安装程序：
```powershell
# Windows
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```
```bash
# macOS / Linux
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```
---
## 技术原理
`server.py` 使用 Anthropic 的 `mcp` Python SDK 中的 **FastMCP** 助手。
- 每个用 `@mcp.tool()` 修饰的函数都成为 Claude 中可调用的工具。
- Claude Desktop 在需要时将 `python server.py` 作为子进程启动。
- 通过 **stdin/stdout** 使用 JSON-RPC 进行通信 - 不打开网络端口。
- 无需身份验证。所有操作都保留在本地机器上。
使用 Anthropic 官方的 MCP Python SDK（FastMCP）构建。
```
Claude Desktop
│
├─[spawn]──→ python server.py
│
├─[stdin]──→ {"method":"tools/call","params":{"name":"read_note","arguments":{"path":"..."}}}
│
└─[stdout]←─ {"result":{"content":[{"type":"text","text":"..."}]}}
```
---
## 安全
- 服务器仅访问**内部**知识库目录的文件。任何试图逃离的路径（例如 `../../sensitive-file`）都在代码级别被阻止。
- 无数据被发送 - 所有操作都在本地运行。
- Claude 无法执行 shell 命令或访问知识库以外的任何内容。
---
## 许可证
MIT - 免费使用、修改和分发。
---
*精心制作。如果这对您有帮助，请考虑分享它或在 GitHub 上点赞。*
*更多工具和教程请访问 [dojicreates.com](https://dojicreates.com/)*
