内容
# Obsidi MCP
通过模型上下文协议（MCP）服务器公开 Obsidian 保险库工具。
## 功能
- **MCP 服务器** - 通过 stdio、HTTP（StreamableHTTP）或 SSE 传输提供保险库工具
- **28+ 内置工具** - 读取、写入、搜索、标记、链接和管理保险库笔记
- **CLI 桥接** - Obsidian 同步历史、文件恢复和差异工具（v1.12+）
- **工具提供商注册表** - 其他插件在运行时注册其他工具
- **保险库资源** - MCP 资源订阅，带有实时保险库更改通知
- **会话持久性** - 连接的 MCP 客户端的热重载恢复
## 要求
- Obsidian 桌面版（不支持移动版 - 使用 Node.js 功能）
- Node.js 18+
- 对于 CLI 桥接：Obsidian CLI v1.12+
## 安装
### BRAT（推荐）
通过 [BRAT](https://github.com/TfTHacker/obsidian42-brat) 安装：
1. 从社区插件安装 BRAT
2. 添加 `cameronsjo/obsidi-mcp` 作为测试插件
3. 在社区插件中启用 Obsidi MCP
### 开发
```bash
git clone https://github.com/cameronsjo/obsidi-mcp.git
cd obsidi-mcp
npm install
npm run build
# For development with auto-rebuild
npm run dev
```
### 链接到 Obsidian
从 Obsidian 保险库的插件文件夹创建符号链接：
```bash
ln -sfn /path/to/obsidi-mcp /path/to/vault/.obsidian/plugins/obsidi-mcp
```
## 使用
1. 在 Obsidian 设置 > 社区插件中启用插件
2. 在插件设置中配置传输（stdio、HTTP 或 SSE）
3. 将您的 MCP 客户端连接到服务器
### 连接 Claude 代码
对于 stdio 传输，请在您的 Claude 代码 MCP 配置中添加：
```json
{
"mcpServers": {
"obsidian": {
"command": "obsidian",
"args": ["--vault", "您的保险库名称", "--mcp"]
}
}
}
```
对于 HTTP 传输：
```json
{
"mcpServers": {
"obsidian": {
"url": "http://localhost:3000/mcp",
"transport": "streamable-http"
}
}
}
```
## 配置
打开设置 > Obsidi MCP 进行配置：
- **传输**：stdio、HTTP（StreamableHTTP）、SSE 或 stdio + HTTP
- **HTTP 端口**：HTTP/SSE 服务器端口（默认：3000）
- **服务器名称**：暴露给 MCP 客户端的服务器名称
- **CLI 桥接**：为同步历史和文件恢复启用 Obsidian CLI 工具
## 可用工具
### 保险库工具（28）
| 类别 | 工具 |
| --- | --- |
| **读取** | `read_note`、`read_note_range`、`get_note_metadata`、`get_active_note` |
| **写入** | `create_note`、`modify_note`、`append_to_note`、`delete_note`、`rename` |
| **搜索** | `search_vault`、`search_by_tag`、`search_by_date` |
| **导航** | `list_notes`、`list_folder`、`get_backlinks`、`get_outgoing_links` |
| **标签** | `list_all_tags`、`manage_tags` |
| **链接** | `suggest_links`、`check_broken_links` |
| **元数据** | `get_vault_stats`、`get_instructions` |
| **语义** | `semantic_search`、`find_similar`（需要 RAG 提供商） |
### CLI 桥接工具（7）
| 工具 | 描述 |
| --- | --- |
| `sync_status` | 检查 Obsidian 同步连接状态 |
| `sync_history` | 获取文件的版本历史 |
| `sync_read` | 读取文件的特定版本 |
| `sync_restore` | 将文件恢复到以前的版本 |
| `file_diff` | 两个文件版本之间的差异 |
| `file_history` | 获取文件修改历史 |
| `file_history_read` | 在特定历史点读取文件 |
## 插件集成
其他插件可以与 Obsidi MCP 注册工具：
```typescript
// 在您的插件的 onload() 中
const mcp = this.app.plugins?.plugins?.['obsidi-mcp'];
if (mcp?.registerToolProvider) {
mcp.registerToolProvider({
id: 'my-plugin',
name: '我的插件',
tools: myToolDefinitions,
});
}
// 在您的插件的 onunload() 中
const mcp = this.app.plugins?.plugins?.['obsidi-mcp'];
mcp?.unregisterToolProvider?.('my-plugin');
```
工具提供商注册后会覆盖具有相同名称的内置工具，允许插件提供增强版本（例如，基于 RAG 的搜索）。
## 架构
```
obsidi-mcp
├── MCPServer（stdio/HTTP/SSE 传输）
│ ├── 工具调度（来自注册表的动态调度）
│ ├── 保险库资源（实时订阅）
│ ├── 补全（路径自动补全）
│ ├── 诱导（确认对话框）
│ └── 日志转发
├── ObsidianTools（28 个内置保险库工具）
├── CLI 桥接（7 个 Obsidian CLI 工具）
├── 保险库资源（直接 app.vault 访问）
└── 工具提供商注册表
├── 内置工具（第 1 层）
├── CLI 桥接工具（第 2 层）
└── 外部提供商（第 3 层，最后赢）
```
## 安全
HTTP/SSE 服务器绑定到 `localhost`，**没有身份验证，没有 TLS，没有访问控制**。它设计用于同一台机器上的 MCP 客户端进行本地使用。
**请勿在未配置安全反向代理的情况下将服务器暴露到网络上。** 任何可以访问 HTTP 端口的人都对您的保险库具有完全的读写访问权限。
如果您需要远程访问，请将服务器置于提供身份验证、TLS、速率限制和基于角色的访问控制的反向代理后面（例如，Caddy、nginx、Cloudflare Tunnel）。
## 故障排除
### 服务器未启动
在 Obsidian 的开发者控制台（Cmd+Option+I）中检查错误。服务器状态在插件设置中可见。
### CLI 桥接不可用
确保已安装 Obsidian CLI（v1.12+）：
```bash
obsidian --version
```
### 端口已被占用
如果端口 3000 被占用，请在插件设置中更改 HTTP 端口。
## 许可证
[PolyForm Noncommercial 1.0.0](LICENSE)
