Obsidian Git MCP

黑曜石Git Vault MCP服务器

你有没有想过如何在你的手机上让克劳德给你的黑曜石金库添加一个待办事项？在旅途中，快速查找你记下的联系人信息？此MCP服务器使您的黑曜石保险库可供Claude和其他AI工具使用，因此您可以在任何地方阅读、搜索和编辑任何对话中的笔记。

一座给予 克劳德 （claude.ai、claude Mobile、claude Code）和其他支持MCP的ai工具对您的 黑曜石 vault——类似于Claude Code与本地文件的交互方式，但通过 模型上下文协议.

• CLAUDE.md 支持 --地点 CLAUDE.md vault中的文件，为Claude提供特定上下文的指令，就像Claude Code或Claude Cowork一样
• 保险库指南 --教授Claude Obsidian惯例、笔记模板和搜索策略
• 认证 --GitHub OAuth使用用户名允许列表控制谁可以访问保管库
• 自动HTTPS --让我们通过Caddy加密证书，无需手动设置

注： 无法加载可能存储在vault存储库中的技能。要使用它们，请像使用其他技能一样，直接在Claude Desktop、Claude.ai或Claude Mobile中添加它们。

你所需要的只是一个现有的 黑曜石Git 同步、小型服务器和 .env 文件。

先决条件

• 黑曜石Git同步 通过设置 黑曜石Git插件 到您选择的Git存储库，例如在Github上。
• 具有公共IP的服务器或服务 （例如Hetzner、AWS、Azure），可以运行和公开Docker容器
• Docker和Docker Compose 已安装在服务器上
• 您选择的（子）域名 DNS指向服务器的IP地址
• 端口80和443 可从互联网访问

入门指南

想要Claude Code指导您完成设置吗？ 安装 克劳德代码 在您的服务器上，然后使用 安装助手提示 而不是手动执行以下步骤。Claude Code将交互式地引导您完成每一步，包括安装先决条件。

步骤1：创建GitHub OAuth应用程序

1. 首选 然后单击 “新OAuth应用程序”
2. 填写以下字段：

- 应用名称: Obsidian MCP Server （或任何你喜欢的名字） - 你的家园: https://your-domain.example.com （替换为您选择的域名） - 授权回调URL: https://your-domain.example.com/oauth/github/callback （替换为您选择的域名，但保留路径）

1. 点击 “注册申请”
2. 复制 客户端ID
3. 点击 “生成新的客户端密钥” 并立即复制秘密（只显示一次）

步骤2：创建GitHub个人访问令牌

1. 首选 个人访问令牌 并创建一个 细粒度个人访问令牌
2. 选择是否希望令牌自动过期（更安全，更费力）或不自动过期（不太安全，更省力）
3. 在下面选择您的vault存储库 “仅选择存储库”
4. 在...之下 仓库权限，set 目录 到 读取和写入
5. 复制令牌

1.

步骤3：克隆和配置

git clone https://github.com/seibert-io/obsidian-github-mcp.git
cd obsidian-github-mcp
cp .env.example .env

编辑 .env 与你的价值观：

# Your domain (Caddy uses this for automatic HTTPS)
SERVER_DOMAIN=your-domain.example.com

# Your vault repository — insert your Personal Access Token from Step 2
GIT_REPO_URL=https://@github.com//.git

# GitHub OAuth App credentials from Step 1
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# GitHub usernames that should have access (comma-separated)
ALLOWED_GITHUB_USERS=your-github-username

# Generate a random secret with min 32 characters, e.g. via  `openssl rand -hex 64`
JWT_SECRET=your-generated-secret

第四步：开始

docker compose up -d

Caddy在首次启动时会自动获得Let's Encrypt证书（大约需要10-30秒）。

步骤5：连接你的AI工具

Claude.ai

1. 首选 设置 → 连接器 → “添加自定义连接器”
2. 输入URL： https://your-domain.example.com/mcp
3. Claude将您重定向到GitHub——使用中列出的帐户登录 ALLOWED_GITHUB_USERS
4. 完成——vault工具将出现在Claude的工具列表中

Claude Code (CLI)

claude mcp add obsidian-vault --transport http https://your-domain.example.com/mcp -s user

添加服务器后，键入 /mcp 在Claude Code中，选择 obsidian-vault 服务器，然后单击 “授权” 通过浏览器完成OAuth登录。

Other MCP-capable tools

请参阅您的工具文档，了解如何注册远程MCP服务器。MCP端点URL为：

https://your-domain.example.com/mcp

更新到较新版本

在您的服务器上，导航到克隆此存储库的目录，然后提取最新更改并重新生成：

cd /path/to/obsidian-github-mcp
git pull
docker compose up -d --build

CLAUDE.md和保险库指南

CLAUDE.md

A. CLAUDE.md 文件在 根 当客户端连接时，您的保管库的数据会自动传递给客户端，就像使用Claude Code或Claude Cowork一样。使用它为Claude保管库提供全范围的指令（命名约定、文件夹结构、首选格式等）。

子目录 CLAUDE.md 文件也受支持。客户端被指示加载并遵循 CLAUDE.md 通过 get_claude_context 工具。

保险库指南

这 get_obsidian_guide 工具和MCP提示教Claude如何使用您的保险库：

• 惯例 --链接语法([[wikilinks]])、封面、标签、标注
• 创建便笺 --zettel、会议、每日、项目和文献笔记的模板
• 搜索策略 --用于不同搜索场景的工具

指南内容存储在 prompts/ 并且可以通过Docker卷挂载进行定制：

volumes:
  - ./my-prompts:/app/prompts

Environment Variables

运作原理

Obsidian (iPhone/Mac)          Docker Host
┌─────────────────┐           ┌──────────────────────────────────┐
│  Obsidian +     │  git      │  ┌────────────────────────────┐  │
│  Obsidian Git   │ ◄──────►  │  │  Git Sync (periodic)       │  │
│  Plugin         │           │  └──────┬─────────────────────┘  │
└─────────────────┘           │         ↕ /vault                 │
                              │  ┌──────────────────────────┐    │
Claude / AI Tool    HTTPS     │  │  MCP Server (Express)    │    │
┌──────────────────┐ ◄──────► │  │  - GitHub OAuth          │    │
│  claude.ai       │  :443    │  │  - Vault tools (MCP)     │    │
│  Claude Code     │          │  └──────────────────────────┘    │
│  Other MCP tools │          │         ↑ reverse proxy          │
└──────────────────┘          │  ┌──────────────────────────┐    │
                              │  │  Caddy (:80/:443)        │    │
                              │  │  - Auto Let's Encrypt    │    │
                              │  └──────────────────────────┘    │
                              └──────────────────────────────────┘

1. 黑曜石 通过以下方式将您的保管库同步到Git存储库 黑曜石Git插件
2. 这 MCP服务器 克隆存储库并定期提取更改
3. 克劳德 （或另一个MCP客户端）通过OAuth连接，并通过MCP工具访问保险库
4. 写操作（创建、编辑、删除、重命名）会自动提交并推回Git
5. CLAUDE.md 文件 在vault中，提供特定于上下文的指令——根级文件在会话开始时自动传递，子目录文件可通过 get_claude_context 工具

技术文档

详细的技术文档可在 docs/:

许可证

麻省理工学院