Obsidian Cloud MCP

黑曜石云MCP


在云中部署具有同步支持的黑曜石MCP服务器。在任何设备（包括手机）上从Claude.ai访问您的保险库。

这是什么？

此存储库提供基础设施即代码来部署基于云的 黑曜石 实例与a 主控程序 （模型上下文协议）服务器。这使得像克劳德这样的人工智能助手可以在任何地方读写你的黑曜石金库。

问题： Obsidian在本地运行，因此当您在移动设备上或使用基于云的AI界面（如Claude.AI）时，AI助手无法访问您的保险库。

解决方案： 在启用同步的情况下在云中运行Obsidian，并通过OAuth保护的MCP服务器公开它。

建筑

该系统由两个主要部分组成：a Hetzner云服务器 运行Obsidian和MCP服务器，以及 Cloudflare工作人员 处理OAuth身份验证。

graph LR
    subgraph "Hetzner Server (Docker Compose)"
        direction TB
        C["Caddy
:80, :443
Auto HTTPS"]
        M["MCP Server
:3000 (internal)
Token Introspection"]
        O["Obsidian
:27123 (internal)
:3001 (GUI)"]
        C --> M --> O
    end

    subgraph "Cloudflare"
        W["Worker
OAuth + Introspect"]
    end

    subgraph "External"
        GH["GitHub OAuth"]
        LE["Let's Encrypt"]
        SYNC["Obsidian Sync"]
    end

    W --> GH
    C --> LE
    O --> SYNC
    M -.->|"Token Introspection"| W

详细组件视图

graph TB
    subgraph "User Devices"
        claude["Claude.ai
(any device)"]
        browser["Browser
(initial setup)"]
    end

    subgraph "Cloudflare Edge"
        worker["Cloudflare Worker
OAuth Provider"]
        kv["KV Store
(tokens, clients)"]
        do["Durable Object
(session state)"]
        worker --- kv
        worker --- do
    end

    subgraph github["GitHub"]
        gh_oauth["GitHub OAuth"]
    end

    subgraph "Hetzner Cloud Server"
        caddy["Caddy
Automatic HTTPS"]
        mcp["MCP Server
(Token Introspection)"]
        obsidian["Obsidian
+ Sync + Local REST API"]
        gui["KasmVNC Web GUI
:3001"]

        caddy -->|":443 → :3000"| mcp
        mcp -->|"REST API :27123"| obsidian
        obsidian --- gui
    end

    claude -->|"1. MCP Request"| caddy
    caddy -->|"2. 401 + Resource Metadata"| claude
    claude -->|"3. OAuth Flow"| worker
    worker -->|"4. GitHub Login"| gh_oauth
    gh_oauth -->|"5. Token"| worker
    worker -->|"6. Access Token"| claude
    claude -->|"7. MCP + Bearer Token"| caddy
    mcp -->|"8. Validate Token"| worker

    browser -->|"One-time setup"| gui

    style worker fill:#f59e0b,color:#000
    style mcp fill:#7c3aed,color:#fff
    style obsidian fill:#7c3aed,color:#fff
    style caddy fill:#22c55e,color:#000

身份验证流程（RFC 7662令牌自检）

MCP服务器和OAuth服务器位于不同的主机上。Claude.ai通过以下方式发现OAuth服务器 受保护资源元数据（RFC 9728），然后通过Cloudflare上的GitHub OAuth进行身份验证。Hetzner MCP服务器通过调用Cloudflare的自检端点来验证令牌。

sequenceDiagram
    participant C as Claude.ai
    participant H as Hetzner
(MCP Server)
    participant CF as Cloudflare
(OAuth Provider)
    participant GH as GitHub
(Identity)

    Note over C: User adds MCP connector
    C->>H: POST /mcp (no token)
    H-->>C: 401 Unauthorized

    C->>H: GET /.well-known/oauth-protected-resource
    H-->>C: {"authorization_servers": ["cloudflare-worker-url"]}

    C->>CF: GET /.well-known/oauth-authorization-server
    CF-->>C: {endpoints...}

    C->>CF: POST /register (Dynamic Client Registration)
    CF-->>C: {client_id, client_secret}

    C->>CF: GET /authorize (+ PKCE)
    CF->>GH: GitHub OAuth redirect
    GH-->>CF: Authorization code
    Note over CF: Verify email ∈ whitelist
    CF-->>C: Authorization code

    C->>CF: POST /token (code + code_verifier)
    CF-->>C: Access token (opaque)

    Note over C: MCP connection established
    C->>H: POST /mcp + Bearer token
    H->>CF: POST /introspect (token)
    CF-->>H: {"active": true, "sub": "..."}
    H-->>C: MCP response (tools, resources)

重要限制

部署后需要手动执行步骤。 基础设施部署、HTTPS和OAuth是完全自动化的，但有两件事需要通过Web GUI手动设置：

1. 黑曜石同步登录 --Obsidian Sync没有无头CLI身份验证。您必须通过Web GUI登录一次。
2. 本地REST API插件 --MCP服务器通过以下方式与Obsidian通信 本地REST API 社区插件。您必须手动安装和配置它：

- 打开黑曜石设置（在Web GUI中） - 首选 社区插件 → 浏览→ 搜索 “本地REST API” - 安装并启用插件 - 首选 设置→ 本地REST API: - 启用 “绑定到所有网络接口” （Docker网络需要） - 复制 API密钥 如插件设置所示 - 跑吧 “配置API密钥” 带有复制密钥的GitHub工作流

完成这两个步骤后，Sync和MCP服务器会自动运行。

先决条件

1. Hetzner云帐户 — 在这里注册
2. 黑曜石同步许可证 — 拿过来
3. GitHub账号 --对于OAuth身份提供者
4. Cloudflare帐户 — 在这里注册 （免费版作品）
5. 域名 --对于HTTPS（子域工作。， mcp.yourdomain.com)
6. SSH密钥对 --用于服务器访问

快速开始

步骤1:Cloudflare Worker设置

Cloudflare Worker充当Claude.ai的OAuth提供者。

1. 创建GitHub OAuth应用程序：

- 首选 - 授权回调URL: https://.workers.dev/callback - 注意 客户端ID 和 客户端密钥

1. 部署Worker：

   cd cloudflare-mcp-server
   npm install
   npx wrangler login

   # Create KV namespace
   npx wrangler kv namespace create OAUTH_KV

   # Update wrangler.jsonc with the KV namespace ID

   # Set secrets
   npx wrangler secret put GITHUB_CLIENT_ID
   npx wrangler secret put GITHUB_CLIENT_SECRET
   npx wrangler secret put COOKIE_ENCRYPTION_KEY  # openssl rand -base64 32

   # Deploy
   npx wrangler deploy

1. 更新GitHub OAuth应用程序 带有已部署工作URL的回调URL。

步骤2:DNS设置

创建一条A记录，将您的域指向您的服务器IP：

（部署后您将获得IP，然后更新DNS。）

第三步：GitHub的秘密

将这些秘密添加到您的分叉存储库中：

步骤4：部署Hetzner服务器

1. 首选 行动 → 部署基础设施 → 运行工作流
2. 输入您的域名（例如。， mcp.yourdomain.com)
3. 等待3-5分钟进行部署+SSL证书

步骤5：配置黑曜石

1. 更新DNS 使用工作流输出中的服务器IP
2. 打开Web GUI: https://:3001

- 用户名： admin - 密码：您的 VNC_PASSWORD

1. 登录黑曜石同步 在GUI中
2. 安装并配置“本地REST API”插件：

- 首选 设置→ 社区插件→ 浏览 - 搜索 “本地REST API” 并安装它 - 启用插件 - 首选 设置→ 本地REST API: - 启用 “绑定到所有网络接口” - 复制 API密钥

1. 运行“配置API密钥”工作流程 使用复制的密钥

步骤6：配置Claude.ai

在Claude.ai设置中，添加自定义MCP连接器：

Claude.ai将自动：

1. 通过受保护的资源元数据发现OAuth服务器
2. 将您重定向到GitHub进行登录
3. 身份验证成功后建立MCP连接

步骤7：禁用Web GUI

初始设置后，禁用Web GUI以提高安全性：

• 首选 行动 → 切换Web GUI访问 → 禁用

电子邮件白名单

访问受到GitHub电子邮件的限制。允许的电子邮件配置在：

cloudflare-mcp-server/src/github-handler.ts

const ALLOWED_EMAILS = new Set(["your-email@example.com"]);

组件

Hetzner服务器

Cloudflare工作人员

MCP服务器环境

GitHub工作流

配置

服务器类型

成本

安全

认证

超文本传输安全协议

• 自动证书 通过Let’s Encrypt
• 自动续订 由Caddy处理
• 无人工干预 必需的

网络

• MCP仅通过HTTPS --通过Caddy的443端口
• 仅限REST API内部 --端口27123未暴露在外
• Web GUI受限 --不需要时可以禁用
• 防火墙规则 --仅打开必要的端口（22、80、443）

故障排除

SSL证书无效：

• 确保DNS A记录指向正确的IP
• 等待5分钟以获得证书
• 检查球童日志： docker logs caddy

MCP服务器返回401：

• 令牌自检可能失败
• 检查MCP日志： docker logs obsidian-mcp
• 验证Cloudflare Worker是否已部署，以及 /introspect 端点工作

OAuth重定向错误：

• 验证GitHub OAuth应用程序回调URL是否与工作URL匹配
• 在中检查电子邮件白名单 github-handler.ts

Web GUI无法访问：

• 检查DOCKER-USER iptables规则是否被阻塞： iptables -L DOCKER-USER -n
• 使用“启用”运行切换Web GUI工作流

清理

要摧毁所有基础设施：

# Via GitHub Actions (recommended)
# Actions → Destroy Infrastructure → type "DESTROY"

# Or via Terraform
cd terraform
terraform destroy

存储库结构

obsidian-cloud-mcp/
├── cloudflare-mcp-server/   # Cloudflare Worker (OAuth + Introspection)
│   ├── src/
│   │   ├── index.ts           # MCP proxy + OAuthProvider
│   │   ├── github-handler.ts  # GitHub OAuth + email whitelist + /introspect
│   │   ├── utils.ts           # OAuth helpers
│   │   └── workers-oauth-utils.ts  # CSRF, state management
│   └── wrangler.jsonc         # Cloudflare config
├── docker/                    # Docker Compose for Hetzner
│   ├── docker-compose.yml
│   ├── Caddyfile
│   └── .env.example
├── mcp-server/                # MCP server Dockerfile
│   └── Dockerfile
├── scripts/
│   ├── cloud-init.yml         # Server provisioning
│   ├── setup-mcp.sh           # Manual setup alternative
│   └── health-check.sh        # Health monitoring
├── .github/workflows/
│   ├── deploy.yml             # Deploy Hetzner infrastructure
│   ├── configure-api-key.yml  # Set Obsidian API key
│   ├── toggle-gui.yml         # Enable/disable Web GUI
│   ├── update.yml             # Update Docker images
│   └── destroy.yml            # Destroy infrastructure
└── terraform/                 # Hetzner IaC

许可证

Apache 2.0——请参阅 许可证