内容
Obsidian 远程服务
[](https://goreportcard.com/report/github.com/shanehull/obsidian-remote)
[](https://github.com/shanehull/obsidian-remote/actions/workflows/lint.yaml) [](https://github.com/shanehull/obsidian-remote/releases)
一个高性能的 Obsidian 保险库的 MCP 服务器，使用 Go 语言编写。该服务器作为 MCP 客户端和 Obsidian [本地 REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) 之间的桥梁。
## 功能特点
- **无头且快速：** 通过本地 REST API 以无头模式运行 Obsidian，所有保险库操作均可进行。
- **符合 RFC 9728 标准：** 实现 OAuth 保护的资源发现。
- **双重传输：** 支持流式 HTTP 和 SSE 传输。
- **安全：** 集成 JWT 和 OAuth 访问令牌验证，支持基于电子邮件的访问控制。
- **服务器端令牌代理：** 客户端无需 OAuth 客户端密钥，服务器在令牌交换过程中注入密钥。
- **谷歌 OAuth：** 通过 JWKS 验证 JWT，借助谷歌的 tokeninfo 端点进行不透明的访问令牌回退。
## 前置条件
- 容器运行时（Docker、Podman 等）。以下示例中使用 Docker Compose。
- 公共 URL（HTTPS），如果从本地网络外部访问。
- （可选）身份验证的谷歌 OAuth 客户端 ID 和密钥。在谷歌云控制台中，创建一个 OAuth 客户端，类型为 **桌面应用程序**，这允许在任意端口上使用 `http://localhost` 重定向 URI，这是 MCP 客户端（Claude Code、OpenCode 等）所必需的。其他 OIDC 提供商仅支持 JWT 验证。如果未配置 OAuth，则服务器将在没有身份验证的情况下运行。
## 资源需求
容器运行无头 Obsidian（Electron/Chromium）和 Xvfb，以及 Go MCP 服务器。Chromium 是主要的内存消耗者。
| 资源 | 最低 | 推荐 |
| :------- | :------ | :---------- |
| RAM | 1 GB | 2 GB |
| CPU | 1 vCPU | 1 vCPU |
| 磁盘 | 3 GB | 5 GB+ |
磁盘使用量包括 Docker 镜像（约 2 GB 基础）加上保险库存储。典型的运行时内存占用约为 300–500 MB，取决于保险库大小。
## 设置
1. **配置环境：**
```bash
cp .env.example .env
```
使用您的配置编辑 `.env`：
**服务器：**
- `PUBLIC_HOST`：此服务器的外部 URL（例如，`https://obsidian.yourdomain.com`）。
**OAuth（可选）：**
- `OAUTH_ISSUER`：您的 OIDC 发行者（例如，`https://accounts.google.com`）。
- `OAUTH_JWKS_URL`：获取公共签名密钥的 URL（例如，`https://www.googleapis.com/oauth2/v3/certs`）。
- `OAUTH_AUTHORIZE_URL`：提供商的授权端点（例如，`https://accounts.google.com/o/oauth2/v2/auth`）。
- `OAUTH_TOKEN_URL`：提供商的令牌端点（例如，`https://oauth2.googleapis.com/token`）。
- `OAUTH_AUDIENCE`：您的 OAuth 客户端 ID。如果未设置，则禁用身份验证。
- `OAUTH_CLIENT_SECRET`：您的 OAuth 客户端密钥（在服务器端用于令牌交换代理）。
- `OAUTH_ALLOWED_EMAIL`：授权访问保险库的特定电子邮件地址。如果未设置，则允许任何已验证用户。
**保险库同步（可选）：**
- `GIT_REPO_URL`：用于保险库同步的 Git 仓库 URL（例如，`git@github.com:user/vault.git`）。
- `GITHUB_PAT`：用于私有仓库的 GitHub 个人访问令牌。
- `VAULT_PATH`：容器内保险库的路径（默认：`/vaults`）。
2. **使用 Docker 运行：**
```bash
docker compose up -d --build
```
##配置
### 流式 HTTP（推荐）
连接到 `/mcp`。OAuth 端点通过 `/.well-known/oauth-protected-resource` 自动发现。
```json "mcpServers": {
"obsidian-remote": {
"url": "https://obsidian.yourdomain.com/mcp"
}
}
}
```
Claude Code：将此内容放入 `settings.json` 中。
OpenCode 在 `opencode.json` 中使用不同的格式：
```jsonc
"$schema": "https://opencode.ai/config.json",
"mcp": {
"obsremote": {
"type": "remote",
"url": "https://obsidian.yourdomain.com/mcp",
"enabled": true,
},
},
}
```
如果配置了 `OAUTH_AUDIENCE`，客户端将自动发现 OAuth 端点。服务器代理令牌交换，客户端无需客户端密钥。
### SSE 传输
支持 SSE 的客户端可以连接到 `/：
```json
"mcpServers": {
"obsidian-remote": {
"url": "https://obsidian.yourdomain.com"
}
}
}
```
## 端点
| 路 | 方法 | 描述 |
| :---------------------------------------- | :-------------- | :------------------------------------------- |
| `/mcp` | POST/GET/DELETE | 流式 HTTP 传输（推荐） `/sse` | GET | SSE 传输 `/message` | POST | SSE 消息端点 |
| `/authorize` | GET | OAuth 授权代理（注入范围） |
| `/token` | POST | 令牌交换代理（注入客户端密钥） |
| `/config` | GET | 动态客户端配置（发行者 + 客户端 ID） |
| `/.well-known/oauth-protected-resource` | GET | RFC 9728 资源元数据 |
| `/.well-known/oauth-authorization-server` | GET | RFC 8414 授权服务器元数据 |
| `/.well-known/mcp` | GET | MCP 特定资源发现 |
| `/register` | POST | 动态客户端注册（RFC 7591） |
## 可用工具
- `list_notes`：列出保险库中的所有笔记。
- `read_note`：读取笔记，可选地按标题、块或前置元数据定位章节。
- `update_note`：创建或更新笔记，可选地按章节定位并执行 `append`/`prepend`/`replace` 操作。
- `delete_note`：永久删除笔记。
- `move_note`：将笔记移动/重命名到新路径。
- `global_search`：在整个保险库中搜索文本或正则表达式。
- `search_replace`：在特定文件中进行有针对性的搜索和替换。
- `manage_frontmatter`：管理 YAML 前置元数据键。
- `manage_tags`：添加或删除笔记的标签。
写入操作（`update_note`、`delete_note`、`search_replace`、`manage_frontmatter`、`manage_tags`、`move_note`）被标记为破坏性操作，提示客户端在执行前请求用户确认。
## 架构
```mermaid
flowchart LR
subgraph clients ["MCP 客户端"]
claude["Claude Code"]
opencode["OpenCode"]
end
subgraph container ["Docker 容器"]
subgraph server ["Go MCP 服务器 :4000"]
transport["/mcp 和 /sse"]
auth["OAuth 中间件"]
end
subgraph obsidian ["无头 Obsidian + Xvfb"]
api["本地 REST API :27124"]
git["obsidian-git"]
vault["/vaults"]
end
end
remote["Git 远程"]
clients -->|HTTPS| transport
transport --> auth
auth -->|"HTTP :271 api
api --> git -->|sync| vault <-->| remote
```
Docker捆绑了 Obsidian（无头）、[本地](https://github.com/coddingtonbear/obsidian-local) 插件（首次启动时自动信任）和 Go MCP 服务器。MCP 服务器支持流式 HTTP（`/mcp`）和 SSE（`/sse`）传输，将 MCP 工具调用转换为内部 Obsidian REST API 的 HTTP 请求。身份验证通过 OAuth 2.0 处理，支持 JWT（ID 令牌）和不透明的访问令牌，均针对谷歌的 tokeninfo进行验证。
