内容
# Obsidian MCP 服务器
一个 Node.js MCP 服务器，为 Claude Code 提供持久的、令牌高效的访问任何 Obsidian 知识库的功能。包括混合全文 + 语义搜索和内置问题跟踪。
## 前置条件
- Node.js 18+
- [Ollama](https://ollama.com) 本地运行，并拉取 `nomic-embed-text`（可选 - 服务器在没有它的情况下也可以工作，仅限 FTS 模式）
```bash
ollama pull nomic-embed-text
```
## 设置
```bash
npm install
npm run build
```
### 在 Claude Code 中注册
将服务器添加到您的 MCP 配置中。在项目根目录中创建一个 `.mcp.json` 文件，或添加到 `~/.claude/mcp.json` 以实现全局访问：
```json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/absolute/path/to/obsidian-brain/dist/server.js"],
"env": {
"VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
}
}
}
}
```
在开发过程中，您可以使用 `tsx` 直接运行 TypeScript 而无需构建：
```json
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/obsidian-brain/src/server.ts"],
"env": {
"VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
}
}
}
}
```
**重要：**
- 服务器脚本和 `VAULT_PATH` 的路径均使用绝对路径
- `VAULT_PATH` 必须指向一个存在的目录 - 如果目录缺失或无效，服务器将立即退出
- 每个知识库一个服务器实例
### 验证连接
配置完成后，重启 Claude Code。服务器应该出现在 MCP 工具列表中。如果连接失败，请检查：
1. `VAULT_PATH` 已设置并指向一个存在的目录
2. 服务器脚本的路径正确且绝对
3. 在 obsidian-brain 目录中已运行 `npm install`（如果使用编译模式，还需要运行 `npm run build`）
4. Node.js 18+ 已可用
## 工具
### 笔记
| 工具 | 描述 |
|---|---|
| `read_note` | 按路径读取笔记，路径相对于知识库根目录 |
| `write_note` | 创建新笔记，自动索引 |
| `update_note` | 在笔记中追加、prepend 或替换一个部分；重新索引 |
| `move_note` | 移动或重命名笔记，更新索引 |
| `list_notes` | 列出文件夹中的笔记，可选递归 |
### 搜索
| 工具 | 描述 |
|---|---|
| `search_vault` | 混合 FTS5 + 向量语义搜索。返回顶部 N 个结果，包含路径和摘录（默认为 5） |
| `reindex_vault` | 完全知识库爬取，重建 FTS5 和向量索引。通过 mtime 跳过未更改的文件 |
### 项目
| 工具 | 描述 |
|---|---|
| `create_project` | 使用启动文件搭建 `02-projects/<name>/` |
### 问题跟踪
| 工具 | 描述 |
|---|---|
| `create_issue` | 创建一个带有类型、优先级和描述的跟踪问题。存储为项目 `issues/` 文件夹中的笔记 |
| `update_issue` | 更改状态、优先级或追加进度笔记。更新 SQLite 记录和 markdown 笔记 |
| `list_issues` | 按状态、类型、优先级或项目筛选问题。按优先级排序 |
**状态：** backlog, not_started, in_progress, code_review, done, blocked
**优先级：** P1（关键）, P2（高）, P3（中）, P4（低）, P5（微不足道）
**类型：** bug, feature, task
## 知识库结构
服务器期望（并使用）以下文件夹布局：
```
00-inbox/ -- 未处理的捕获
01-ideas/ -- 原始想法
02-projects/ -- 活跃项目（每个项目都在其自己的子文件夹中）
<project>/
issues/ -- 项目范围内的問題
03-research/ -- 按领域划分的外部知识
04-knowledge/ -- 提炼的长期概念
05-life/ -- 个人规划
06-finance/ -- 财务策略
07-work/ -- 专业材料
meta/ -- 系统笔记
issues/ -- 全局问题（不绑定到特定项目）
```
## 工作原理
### 搜索
1. `reindex_vault` 遍历所有 `.md` 文件，剥离 frontmatter，通过 Ollama 嵌入，并存储在 SQLite 中（FTS5 + sqlite-vec）
2. `search_vault` 并行运行关键字（FTS5）和语义（向量余弦）查询，合并和去重结果
3. Claude 仅对相关结果调用 `read_note` - 这是令牌效率机制
如果 Ollama 不可用，服务器会自动回退到仅限 FTS5 的搜索。如果 `sqlite-vec` 无法加载（例如缺少原生二进制），服务器也会回退到仅限 FTS 的模式。
### 问题跟踪
问题存储在两个地方：
- **Markdown 笔记** 在 `02-projects/<project>/issues/` - 可在 Obsidian 中浏览，包含 frontmatter 元数据和笔记日志。在更新问题时保持同步。
- **SQLite 表** 在 `.vault-index.db` - 启用快速结构化查询（按状态、优先级、类型、项目筛选）
### 安全
- 所有笔记路径都经过验证，以确保在知识库边界内 - 拒绝路径遍历攻击（例如 `../../etc/passwd`）
- FTS5 搜索输入经过净化处理，以防止查询操作符注入
### 索引
每个知识库都将其索引存储在 `<VAULT_PATH>/.vault-index.db`。该文件由服务器生成，不应提交到版本控制系统中。
## CLAUDE.md
在您的知识库根目录中放置一个 `CLAUDE.md`，其中包含 Claude 的说明。它在每个会话中自动加载。示例规则：
- 永远不要删除笔记 - 如果不确定，请移动到 `00-inbox/`
- 搜索后再创建 - 避免重复笔记
- 使用 MCP 工具而不是直接读写文件
- 尊重文件夹角色
## 依赖项
| 包 | 用途 |
|---|---|
| `@modelcontextprotocol/sdk` | MCP 服务器框架 |
| `better-sqlite3` | SQLite 驱动程序（FTS5） |
| `sqlite-vec` | SQLite 的向量相似性扩展 |
| `zod` | 工具参数的模式验证 |
| `tsx` | 直接运行 TypeScript |
| `typescript` | 编程语言 |
