内容
# Obsidian MCP 服务器
<div align="center">
一个适用于 Obsidian.md 的模型上下文协议（MCP）服务器，允许像 Claude 这样的 AI 助手与您的 markdown 保险库进行交互。
[功能](#功能) • [安装](#安装) • [配置](#配置) • [使用](#使用) • [文档](#文档)
</div>
## 概述
该 MCP 服务器为 AI 助手提供无缝的 Obsidian 集成，通过一套全面的工具实现与 markdown 笔记的自然交互。采用文件系统可靠性与可选 REST API 功能相结合的混合架构。
## 功能
### 10 种工具
#### 📝 笔记操作
- **读取笔记** - 读取笔记内容和元数据（大小、时间戳） • *文件系统*
- **写入笔记** - 创建或覆盖笔记，具备安全保护 • *文件系统*
- **追加笔记** - 追加内容，可选时间戳 • *文件系统*
- **更新前置信息** - 添加、更新或删除 YAML 前置信息字段 • *文件系统*
- **应用模板** - 应用模板，支持变量替换 • *文件系统*
#### 🔍 搜索与发现
- **列出笔记** - 列出笔记，支持通配符模式、排序和日期过滤 • *文件系统*
- **搜索笔记** - 全文搜索，支持正则表达式和上下文行 • *文件系统*
- **获取标签** - 从前置信息和内联 #标签中提取和分析标签 • *文件系统*
#### 📅 每日笔记
- **获取每日笔记** - 获取或定位每日笔记，自动检测路径 • *混合（API + 文件系统）*
- **追加到每日笔记** - 快速追加到今日的每日笔记，带时间戳 • *混合（API + 文件系统）*
> **图例：**
> - *文件系统* - 在文件系统模式和混合模式下均可工作（无需 API）
> - *混合（API + 文件系统）* - 可用时使用 REST API，失败后回退到文件系统
> - *仅 API* - 需要 Obsidian REST API 插件和 Obsidian 运行中
## 安装
### erequisites
- Node.js 18 或更高版本
- 一个 Obsidian 保险库
- Claude Desktop 或另一个 MCP 兼容的客户端
- （可选）[Obsidian 本地 REST API 插件](https://github.com/coddingtonbear/obsidian-local-rest-api)，用于增强功能
### 快速开始
1. **克隆并安装**
```bash
git clone https://github.com/yourusername/obsidian-mcp.git
cd obsidian-mcp
npm install
```
2. **构建项目**
```bash
npm run build
```
## 配置
### 基本设置（仅文件系统）
对于基本功能，仅需设置保险库路径：
**创建 `.env` 文件**（用于测试）：
```env
OBSIDIAN_VAULT_PATH=/absolute/path/to/your/vault
```
### 高级设置（混合模式 - 推荐）
对于自动每日笔记检测和插件集成等增强功能：
1. **安装 Obsidian 本地 REST API 插件**
- 打开 Obsidian → 设置 → 社区插件
- 搜索“本地 REST API”
- 安装并启用插件
- 从插件设置中复制 API 密钥
2. **配置环境**
```env
OBSIDIAN_VAULT_PATH=/absolute/path/to/your/vault
OBSIDIAN_API_URL=http://127.0.0.1:27123
OBSIDIAN_API_KEY=your-api-key-here
OBSIDIAN_VERIFY_SSL=false
```
### Claude Desktop 设置
添加到您的 Claude Desktop 配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
**仅文件系统模式：**
```json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/absolute/path/to/obsidian-mcp/dist/server.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault",
"LOG_LEVEL": "ERROR"
}
}
}
}
```
**混合模式（推荐）：**
```json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/absolute/path/to/obsidian-mcp/dist/server.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault",
"OBSIDIAN_API_URL": "http://127.0.0.1:27123",
"OBSIDIAN_API_KEY": "your-api-key-here",
"LOG_LEVEL": "ERROR"
}
}
}
}
```
重启 Claude Desktop 后生效。
## 使用
配置完成后，您可以通过 Claude Desktop 自然地与 Obsidian 保险库交互：
```
"读取昨天的每日笔记"
"创建名为'MCP 集成'的新项目笔记，应用标准模板"
"搜索包含'TODO'的所有笔记，位于我的项目文件夹中"
"在今日的每日笔记中添加任务：查看 MCP 文档"
"列出所有标记为 #ai 或 #mcp 的笔记"
"更新项目笔记的前置信息，添加状态：进行中"
"将我的会议模板应用于名为'Team Sync 2025-11-02'的新笔记"
```
## 文档
- **[使用指南](./USAGE.md)** - 详细的设置、配置和使用说明
- **[架构](./CLAUDE.md)** - 项目结构和模式
- **[路线图](./.claude/ROADMAP.md)** - 计划的功能和下一步
## 开发
```bash
# 以自动重载模式启动开发环境
npm run dev
# 构建生产环境
npm run build
# 运行测试
npm test
# 运行测试并生成覆盖率报告
npm run test:coverage
# 类型检查
npm run typecheck
```
## 故障排除
### 常见问题
**"保险库路径未找到" 错误**
- 确保保险库路径是绝对路径（非相对路径）
- 检查目录是否包含 `.obsidian` 文件夹
- 在 Windows 上，使用正斜杠：`C:/Users/YourName/vault`
**"API 不可用" 警告**
- 服务器自动回退到文件系统模式
- 安装 Obsidian 本地 REST API 插件以获取增强功能
- 验证 Obsidian 是否正在运行且插件已启用
**权限错误**
- 检查保险库目录的文件权限
- 确保保险库不在受限位置（例如系统文件夹）
**Claude Desktop 上未显示工具**
- 在配置更改后完全重启 Claude Desktop
- 验证 `dist/server.js` 的路径是否为绝对路径且正确
- 在 Claude Desktop 的开发者控制台中检查日志
有关更详细的故障排除，请参见 [USAGE.md](./USAGE.md)。
## 架构
使用 TypeScript 和 Node.js 构建，包含：
- **@modelcontextprotocol/sdk** - MCP 协议实现
- **gray-matter** - YAML 前置信息解析
- **minimatch** - 通配符模式匹配
- **axios**（可选）- REST API 客户端
- **zod** - 运行时类型验证
服务器采用混合架构，具备：
- **文件系统优先方法**，确保可靠性和速度
- **可选 REST API 集成**，提供高级功能
- **模块化工具组织**，便于维护
- **基类模式**，实现一致的错误处理
- **全面的日志记录**，使用 Winston
- **自动重试逻辑**，处理暂时性错误
### 运行模式
- **仅文件系统**：直接文件访问（离线支持）
- **混合模式**：优先使用 API，文件系统作为备用（推荐）
- **优点**：自动每日笔记检测、插件集成、优雅降级
## 贡献
欢迎贡献！请参阅以下开发设置：
1. 分叉仓库
2. 克隆您的分叉
3. 安装依赖：`npm install`
4. 创建功能分支
5. 进行更改并添加测试
6. 运行测试：`npm test`
7. 确保构建成功：`npm run build`
8. 提交拉取请求
## 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](./LICENSE) 文件。
## 致谢
由 Anthropic 为 [模型上下文协议](https://modelcontextprotocol.io) 生态系统构建。
特别感谢：
- Obsidian 社区提供的灵感和反馈
- [Obsidian 本地 REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) 插件作者 coddingtonbear
- 其他 MCP 服务器实现提供的模式和想法
---
<div align="center">
**有疑问？** 打开 [问题](../../issues) 或发起 [讨论](../../discussions)
为 MCP 社区打造 ❤️
</div>
