内容
# obsidian-livesync-mcp
用于通过CouchDB访问Obsidian vault的远程MCP服务器，适用于[Self-hosted LiveSync](https://github.com/vrtmrz/obsidian-livesync)。与Claude Code、Claude.ai以及任何兼容MCP的客户端配合使用。
无需在服务器上安装Obsidian桌面应用程序 — 直接连接到CouchDB。
## 架构
```
Obsidian (手机/桌面) <-> CouchDB <-> MCP 服务器 <-> Claude Code / Claude.ai
```
Obsidian客户端通过LiveSync插件与CouchDB实例同步。该MCP服务器直接读写CouchDB，提供20种工具来管理您的vault — 无需在服务器端使用Obsidian REST API或桌面应用程序。
## 功能
### 笔记
- **搜索** — 全文搜索（文本/正则表达式）
- **获取** — 获取内容、属性和统计信息（.md/.base/.canvas）
- **创建笔记** — 创建带有前置信息的笔记
- **更新笔记** — 修改（覆盖/追加/前置/后置/搜索替换）
- **删除笔记** — 删除笔记
- **移动笔记** — 移动/重命名
- **复制笔记** — 复制
- **列出笔记** — 列出文件，支持文件夹/扩展名过滤
### 属性和标签
- **管理属性** — 获取/设置/删除前置信息属性
- **管理标签** — 添加/删除/列出标签
- **获取所有标签** — 获取所有vault标签及其计数
### 图谱和链接
- **获取链接** — 获取外出/进入链接
- **获取链接图谱** — 获取整个vault图谱
- **查找孤立笔记** — 查找无链接笔记
- **查找中心笔记** — 查找最具连接性的笔记
### 画布
- **画布节点** — 添加/删除画布节点
- **画布边** — 添加/删除画布边
### 其他
- **vault统计** — vault统计信息
- **从模板创建** — 从模板创建，支持变量替换
- **列出模板** — 列出可用模板
## 前置条件
- 具有Obsidian LiveSync数据的CouchDB
- Python 3.11+
## 设置
### 1. 安装
```bash
git clone https://github.com/YOUR_USERNAME/obsidian-livesync-mcp.git
cd obsidian-livesync-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
### 2. 配置
```bash
cp .env.example .env
# 编辑 .env 文件，填写您的设置
```
| 变量 | 描述 |
|---|---|
| `COUCHDB_URL` | CouchDB URL（例如 `http://localhost:5984`） |
| `COUCHDB_USER` | CouchDB 管理员用户名 |
| `COUCHDB_PASSWORD` | CouchDB 管理员密码 |
| `COUCHDB_DATABASE` | 数据库名称（默认为 `obsidian`） |
| `MCP_API_KEY` | MCP 客户端（如 Codex）共享的 bearer token |
| `OAUTH_PASSWORD` | OAuth 同意密码（留空以禁用 OAuth） |
| `OAUTH_CLIENT_ID` | 预注册客户端的 OAuth 客户端 ID |
| `OAUTH_CLIENT_SECRET` | OAuth 客户端密钥 |
| `MCP_SERVER_URL` | 服务器的公共 HTTPS URL |
| `MCP_HOST` | 绑定地址（默认为 `0.0.0.0`） |
| `MCP_PORT` | 端口（默认为 `8484`） |
### 3. 运行
```bash
python run.py
```
### 4. Systemd 服务（可选）
```bash
sudo cp obsidian-mcp.service /etc/systemd/system/
# 编辑服务文件：设置 User 和路径
sudo systemctl daemon-reload
sudo systemctl enable obsidian-mcp
sudo systemctl start obsidian-mcp
```
## 连接客户端
### Codex
在Codex运行的环境中设置相同的API密钥，然后在 `~/.codex/config.toml` 中添加可流式传输的HTTP MCP服务器：
```toml
[mcp_servers.obsidian]
url = "https://your-server/mcp"
bearer_token_env_var = "MCP_API_KEY"
```
Codex支持已使用此可流式传输的HTTP配置和存储在 `MCP_API_KEY` 环境变量中的bearer token进行验证。
对于直接要求自定义标头的MCP客户端，请使用：
| 键 | 值 |
| --- | --- |
| `Authorization` | `Bearer your_api_key` |
将 `your_api_key` 替换为服务器上配置的 `MCP_API_KEY` 的确切值。
### Claude.ai（网页）
1. 设置 > 连接器 > 添加自定义连接器
2. URL：`https://your-server/mcp`
3. 客户端ID和客户端密钥来自您的 `.env` 文件
## 认证
服务器支持两种认证模式：
1. **Bearer API密钥** - 设置 `MCP_API_KEY`，客户端必须发送 `Authorization: Bearer <MCP_API_KEY>`。如果同时存在bearer和OAuth设置，则此模式优先。
2. **OAuth 2.1** - 设置 `OAUTH_PASSWORD` 和OAuth客户端设置，以使用现有的授权代码流 + PKCE。
如果既未设置 `MCP_API_KEY` 也未设置 `OAUTH_PASSWORD`，则服务器在启动时失败，而不是运行开放。
### 当前限制
开箱即用，OAuth仅支持 **Claude** （Claude.ai 和 Claude Code）作为客户端。预注册的OAuth客户端具有硬编码的 `redirect_uris` 以匹配Claude的回调URL和 `scope: claudeai`。
### 添加其他MCP客户端
要支持其他客户端，您可以：
1. **预注册其他客户端** - 在 `oauth_provider.py` 的 `__init__` 中添加更多客户端，并为您的客户端设置适当的 `redirect_uris`。
2. **启用动态客户端注册（DCR）** - 在 `server.py` 中，将 `ClientRegistrationOptions(enabled=False, ...)` 更改为 `enabled=True`。这允许任何MCP兼容的客户端自动注册。注意：这意味着任何知道您的服务器URL的人都可以注册客户端。
## 许可证
Apache 2.0
