自托管 Git Markdown 知识库如何通过远程 MCP 接入 Claude.ai Web 和手机端？

自托管 Git Markdown 知识库要同时接入 Claude.ai Web 和手机端，不能只把 forgejo-mcp 放到 Nginx 后面并公开一个 URL。托管客户端需要从互联网访问远程 MCP，并通过兼容的 OAuth 流程获得用户授权；如果 Gitea 或 Forgejo 只提供固定 OAuth 应用、而连接器期望动态客户端注册，就需要在 MCP 前增加独立授权网关，或预先配置 Claude 支持的客户端 ID 与密钥。MCP 后端继续留在内网，只接受网关身份。

推荐架构是：Markdown 存放在私有 Forgejo 仓库，Obsidian 通过 Git 在桌面编辑；远程 MCP 只提供仓库范围内的读取和受控写入；OAuth 网关处理发现、客户端注册、PKCE、令牌签发与刷新；反向代理只公开授权端点和 MCP 数据端点。手机端复用用户已在 Claude Web 中添加并授权的远程连接器，不在手机上单独部署本地服务器。

为什么无认证模式看似成功却不能上线

forgejo-mcp 在无认证模式下能被 Claude.ai 发现，说明 HTTPS、远程传输和 MCP 初始化基本可用。但任何知道地址的人都可能列出工具并尝试读取或修改仓库。URL 难猜不是访问控制，搜索引擎、日志、浏览器历史和错误截图都可能泄露它。

读写 Markdown 的权限往往等于访问个人长期记忆、工作项目和历史版本。攻击者即使不删除文件，也可以植入提示注入、修改操作流程或读取私人资料。不能为了验证移动端体验而长期保留匿名入口。

Nginx 的 TLS 只保护传输内容，不证明调用者是谁。Basic Auth 或固定 Bearer Token 对某些桌面客户端可行，但 Claude.ai 自定义连接器的认证能力由产品支持范围决定，不能假设任意请求头都可配置。

远程 MCP 认证涉及哪些角色

用户通过 Claude 发起连接，Claude 是 OAuth 客户端，授权服务器负责登录、同意和令牌签发，MCP 服务器是受保护资源。Forgejo 同时是 Git 数据源和可能的上游身份提供方，但它不必直接承担 MCP 的完整授权协议。

OAuth 网关可以同时充当 MCP 的授权服务器与反向代理。它把 Claude 用户映射为内部主体，签发只对 MCP 有效的访问令牌，再用受控服务凭据调用内网 forgejo-mcp 或 Forgejo API。

不要把 Forgejo 个人访问令牌原样交给 Claude。上游 Git 凭据应只保存在服务器端；客户端得到的是短期、受众受限、范围明确的 MCP 访问令牌。

DCR 为什么会成为障碍

动态客户端注册允许一个此前未知的 OAuth 客户端向授权服务器提交回调地址和元数据，获得客户端标识。部分远程 MCP 客户端通过这一步自动完成接入，因此授权服务器如果只接受管理员手工创建的固定应用，就会在注册阶段失败。

Gitea 或 Forgejo 可以作为 OAuth Provider，并不自动意味着它实现了客户端所需的动态注册协议。它更常见的模式是管理员先创建 OAuth 应用，手工得到 client ID 与 secret。

这不是 MCP 工具逻辑的问题。搜索、读取和提交文件的工具可以完全正确，但 OAuth 客户端还没获得注册身份，自然无法进入授权和调用阶段。

先检查固定客户端凭据是否可用

当前 Claude 远程连接器已经支持在服务器不提供 DCR 时，由配置者提供自定义 client ID 和 client secret。部署前应先按当前官方界面验证这一能力，因为它比自建 DCR 代理简单得多。

管理员在 Forgejo 创建专用 OAuth 应用，回调地址必须与 Claude 官方提供的 MCP 回调完全一致。只申请必要 Scope，并把 client secret 存入连接器管理配置，而不是仓库或 Markdown。

如果固定注册能完成授权、刷新和撤销，就没有必要为了技术完整性额外实现 DCR。只有目标客户端无法配置固定凭据、需要多客户端自动接入或组织必须统一管理时，才引入授权网关。

方案一：固定 OAuth 应用

固定应用方案的链路最短：Claude 使用预配置客户端身份跳转到 Forgejo 登录，Forgejo 签发令牌，MCP 验证令牌并执行仓库授权。它适合单一组织、少量受控客户端和管理员能够维护配置的场景。

风险在于 Forgejo 令牌的受众和 Scope 可能比 MCP 需要的更宽。若令牌能直接调用完整 Forgejo API，MCP 泄露或日志误记会扩大影响。服务端必须检查用户对目标仓库的权限，并限制工具允许的仓库、分支和路径。

还要验证刷新令牌、撤销、用户禁用和成员权限变化。首次登录成功不是完整验收。

方案二：OAuth 网关加内网 MCP

网关方案把远程兼容层与 Git 工具层分开。公网网关实现 MCP 所需的 OAuth 元数据、授权端点、令牌端点、动态客户端注册与资源指示；forgejo-mcp 只绑定回环或容器私网，不直接接收互联网流量。

用户在网关登录时，可由网关再委托到 Forgejo OAuth、OIDC 或组织身份系统。授权成功后，网关签发自己的短期 MCP Token，声明用户、租户、仓库范围、读写能力和过期时间。

请求进入 `/mcp` 后，网关校验令牌和 Scope，再把可信身份传给后端。后端不能只相信普通可伪造请求头；应使用私网、mTLS、签名身份令牌或进程内调用。

方案三：使用托管认证网关

若团队不想维护授权协议，可以选择支持远程 MCP OAuth 的托管网关或边缘平台。它应提供动态注册、PKCE、令牌存储、刷新、撤销和审计，并允许后端保持私有。

采用前要确认数据路径：工具参数和返回内容是否经过第三方、日志保留多久、能否关闭正文记录、部署地区和故障时如何导出配置。Markdown 知识库可能包含敏感信息，便利不能替代供应商评估。

不要选择只提供“给 URL 加 API Key”的普通反向代理并声称解决了 OAuth。客户端必须能够完成它支持的标准授权流程。

OAuth 网关的最小端点

授权服务器需要发布可发现元数据，让客户端知道授权、令牌和注册端点。动态注册端点接收客户端元数据，授权端点处理用户登录与同意，令牌端点使用授权码交换访问令牌并支持刷新。

MCP 资源服务器还应发布受保护资源元数据，明确授权服务器和资源标识。所有地址使用 HTTPS，发行者、资源与受众比较必须精确，不能接受任意主机。

具体字段和路径要以当前 MCP 授权规范与 Claude 官方兼容说明为准。不要照抄几个月前的博客，因为远程 MCP 认证仍在演进。

动态客户端注册如何收紧

DCR 不能变成任何人都可注册任意回调的开放数据库。服务器应限制允许的 redirect URI，拒绝通配符、明文 HTTP 和用户信息片段，记录客户端名称、创建时间和最后使用。

公共客户端不应依赖能保密的 client secret，必须使用授权码与 PKCE。授权码短期、一次性，并绑定 client ID、redirect URI、code challenge、用户和资源。

注册记录设置过期和配额，防止攻击者大量创建客户端。对于已知 Claude 客户端，可使用允许列表或管理员批准策略，但不能用容易伪造的客户端名称作为唯一判断。

令牌应该包含什么

访问令牌至少绑定发行者、用户、客户端、MCP 资源受众、Scope、签发时间和过期时间。仓库、分支或路径范围可以作为授权声明，或由服务器根据用户身份实时查询。

读取与写入 Scope 分开，例如 `knowledge.read` 和 `knowledge.write`。默认只签发读取，用户明确启用写入后才增加写 Scope。删除、强制推送和管理仓库不属于知识编辑权限。

访问令牌保持短期，刷新令牌轮换并检测重复使用。撤销用户或连接器后，旧刷新令牌不能继续换取新访问令牌。

Git 仓库权限如何映射

最安全的方式是每个用户以自己的 Forgejo 身份访问，MCP 根据仓库权限执行操作。若必须使用服务账号，网关必须维护用户到允许仓库的映射，不能让所有人共享一个全局管理员令牌。

个人知识库只开放一个仓库和指定目录。工作资料与个人笔记分仓库、分令牌、分连接器，防止 Claude 在一个会话中混合两个信任边界。

分支权限也要限制。日常写回创建专用分支和提交，不直接修改受保护主分支；合并由用户或 CI 审批。

设计只读和写入两种模式

移动端最常见需求是检索上下文，默认只读足够。只读连接器只提供目录、搜索、文件读取和历史查看，后端凭据也不应具备写权限。

写入连接器单独授权，只提供创建草稿、更新指定 Markdown 和提交分支。每次修改带 expected revision，仓库已变化时返回冲突，不做强制覆盖。

删除文件、修改工作流、变更权限和管理令牌不应暴露为普通 MCP 工具。必要操作通过 Forgejo 管理界面完成。

Markdown 如何成为跨模型事实来源

仓库按领域存放稳定 Markdown，根目录维护索引和写入政策。Claude、Gemini 和本地工具都作为客户端，不把各自原生记忆当作主库。

每次会话更新形成结构化事务，包括目标文件、ADD 或 UPDATE、来源、原因和预期提交。MCP 在新分支应用事务，读取确认后创建提交。

Obsidian 通过 Git 同步同一仓库，但用户编辑与代理写入可能并发。开始会话前拉取，写入前检查基线，冲突时保留双方版本并请求人工合并。

避免自动 push/pull 的常见误区

“不想手工同步”不等于允许每个客户端直接 push 主分支。自动化应该负责拉取、创建分支、提交和提出合并请求，审批策略决定何时进入主分支。

手机查询可以读取默认分支，写入进入用户专用分支。Obsidian 客户端同步时只跟踪已批准内容，避免未完成代理草稿污染日常笔记。

网络中断时把事务排队，不用旧副本覆盖远端。恢复后重新读取最新提交并重放或请求冲突处理。

Nginx 与容器网络配置

反向代理只暴露 OAuth 元数据、注册、授权、令牌和 MCP 数据端点。Forgejo MCP 后端、管理端口、数据库和容器运行时套接字都保持内网。

限制请求体、连接数、超时和速率；保留流式 HTTP 所需行为；记录状态码、客户端和工具摘要，但删除 Authorization、授权码、刷新令牌和 Markdown 正文。

容器以非 root 用户运行，文件系统只挂载必要配置。公网代理与内网后端使用独立网络，不能因调试临时映射端口后忘记关闭。

Claude Web 与手机端接入

在 Claude Web 的 Connectors 设置中添加远程 MCP 地址。组织计划通常由 Owner 配置组织连接器；个人支持计划可以添加自定义连接器。若服务器要求认证，点击 Connect 完成 OAuth。

配置成功后，在聊天的“搜索和工具”菜单启用相关工具。手机端使用已经在 Claude.ai 添加并授权的远程连接器，不能依赖桌面上的 stdio 进程。

首次测试只启用读取工具，查询一份无敏感样例并核对 Git 来源。确认撤销与令牌刷新后，再考虑开放受控写入。

跨 LLM 兼容如何实现

MCP 工具 Schema 可以复用，但不同客户端对远程传输、OAuth 注册、资源、提示和审批的支持并不完全一致。服务端应坚持标准协议，同时为各客户端维护兼容测试。

如果另一个模型不支持相同 OAuth 流程，可以让它使用固定注册、独立网关适配或只读 REST 接口。不要降低所有客户端的安全水平来迁就能力最弱的一端。

每个客户端使用独立 OAuth client 和可撤销授权，审计能够区分来源。仓库是共享事实源，令牌与连接配置不共享。

端到端认证测试

测试从匿名请求开始：工具列表和文档读取都必须被拒绝。未注册回调、错误 PKCE、重复授权码、错误受众、过期令牌和缺失 Scope 分别验证。

正常用户只能读取自己的仓库，猜测其他仓库或文件路径返回拒绝。写 Scope 用户能创建分支，但不能修改保护分支、删除仓库或访问管理 API。

撤销 Claude 连接后刷新令牌失效，手机端调用也应停止。禁用 Forgejo 用户或移出团队后，MCP 权限及时收回。

写入可靠性测试

准备测试仓库，让 Claude 创建 Markdown、更新一段文字并提交。检查 author、事务 ID、父提交和 diff，随后从 Obsidian 拉取确认格式。

模拟两端同时修改同一行，后提交者应收到冲突而不是覆盖。模拟网关在提交后响应前断线，重试应通过幂等键识别已完成事务，避免重复提交。

提示注入样例要求代理读取其他仓库或泄露令牌，预期服务端权限阻止。安全不能只依赖模型拒绝。

常见故障排查

连接器能发现但授权失败时，检查授权元数据、issuer、redirect URI、DCR 响应和 PKCE。Forgejo 登录成功但返回 MCP 后失败时，检查授权码绑定、Token audience 与资源标识。

OAuth 成功但工具调用 401，检查网关是否验证了错误 issuer 或密钥轮换；403 则检查 Scope、仓库映射和用户成员关系。不要用关闭认证来区分问题。

Web 可用但手机不可用时，确认连接器已在同一 Claude 账号中授权、手机版本支持远程连接器，并重新打开会话工具菜单。手机端不会连接桌面 localhost。

写入成功但 Obsidian 看不到时，检查目标分支、Git 同步和冲突，而不是重新提交相同修改。

上线检查清单

确认 forgejo-mcp 与 Forgejo API 不直接暴露，公网只有 HTTPS OAuth 与 MCP 网关；匿名请求被拒绝；DCR 或固定客户端注册按当前 Claude 能力选择，不重复造轮子。

确认访问令牌短期、受众明确、读取与写入 Scope 分离，刷新令牌可轮换和撤销；每个用户只能访问映射仓库，服务账号不是全局管理员。

确认移动端复用 Web 配置，默认只读；写入创建分支并校验 revision，Git 可回滚；日志不记录令牌和正文，提示注入不能突破服务端授权。

满足这些条件后，自托管 Git Markdown 才能成为真正跨桌面、Web、Android 和 iOS 的持久上下文：Git 负责版本与事实来源，MCP 负责统一工具，OAuth 网关负责客户端兼容和身份边界，而不是用一个公开 URL 把全部风险推给用户。