Hint-Services-obsidian-github-mcp

Obsidian GitHub MCP

一个模型上下文协议（MCP）服务，可将 AI 助手连接到包含 Obsidian 库的 GitHub 仓库。此服务可与存储在 GitHub 上的知识库无缝集成，让 AI 助手能够读取、搜索和分析你的 Obsidian 笔记与文档。

为什么选择此工具？

许多 Obsidian 用户会将库保存在 GitHub 上，以便备份、管理版本和协作。此 MCP 服务打通了托管在 GitHub 上的 Obsidian 库与 AI 助手之间的隔阂，支持：

• 知识库访问：从你的 Obsidian 库中获取特定笔记和文档
• 智能搜索：在整个知识库中查找相关内容
• 演变追踪：查看你的想法和笔记如何随时间发展
• 任务集成：连接问题和项目管理工作流

功能

• GitHub 仓库访问：连接到任何包含 Obsidian 库的 GitHub 仓库
• 类型安全的实现：使用 TypeScript 编写，包含全面的类型定义
• 输入验证：使用 Zod 模式对所有 API 输入进行可靠验证
• 错误处理：妥善处理错误并提供清晰的提示信息
• MCP 集成：完全兼容 Claude、Cursor、Windsurf、Cline 和其他 MCP 宿主

可用工具

知识库访问

• getFileContents：从你的 Obsidian 库中获取特定笔记、文档或文件的内容
• searchFiles：增强型搜索，支持多种模式：
  • filename：按精确文件名查找文件（非常适合“OKR 2025”这类搜索）
  • path：在文件路径中的任意位置搜索
  • content：在文件内容中搜索
  • all：全面搜索文件名、路径和内容

项目管理集成

• searchIssues：搜索与知识库项目相关的问题和讨论
• getCommitHistory：通过详细的提交历史和差异，追踪知识库随时间的演变

使用场景

面向知识工作者

• 研究助手：AI 可访问你的研究笔记和参考资料
• 写作支持：从知识库中提取相关背景信息
• 想法发展：追踪概念如何在你的笔记中演变

面向开发者

• 文档访问：获取项目文档和技术笔记
• 学习日志：访问你的学习笔记和代码示例
• 项目规划：与 GitHub 问题集成，实现全面的项目管理

面向学生和学者

• 学习材料：访问讲义和学习指南
• 研究论文：获取研究笔记和引文
• 协作：使用存储在 GitHub 上的共享知识库开展协作

安装

使用 Smithery（推荐）

安装 Obsidian GitHub MCP 的最简单方式是使用 Smithery：

# For Claude Desktop
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client claude

# For Cursor
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client cursor

# For Windsurf
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client windsurf

# For Cline
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client cline

手动安装

npm install obsidian-github-mcp

配置

将服务添加到 MCP 设置文件，并使用以下配置：

{
  "mcpServers": {
    "obsidianGithub": {
      "command": "npx",
      "args": ["-y", "obsidian-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "your-github-token",
        "GITHUB_OWNER": "your-github-username",
        "GITHUB_REPO": "your-obsidian-vault-repo"
      }
    }
  }
}

必需的环境变量

• GITHUB_TOKEN：你的 GitHub 个人访问令牌（在此创建）
• GITHUB_OWNER：GitHub 仓库的所有者或组织
• GITHUB_REPO：包含 Obsidian 库的仓库名称

GitHub 令牌权限

你的 GitHub 令牌需要具备以下权限：

• repo（用于私有仓库）或 public_repo（用于公共仓库）
• read:org（用于访问组织仓库）

工作流示例

访问每日笔记

{
  "tool": "getFileContents",
  "arguments": {
    "filePath": "Daily Notes/2024-01-15.md"
  }
}

按名称查找文件（非常适合“OKR 2025”示例！）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "OKR 2025",
    "searchIn": "filename"
  }
}

按路径查找文件

{
  "tool": "searchFiles",
  "arguments": {
    "query": "Daily Notes",
    "searchIn": "path"
  }
}

查找某个主题的研究资料（内容搜索）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "machine learning algorithms",
    "searchIn": "content",
    "perPage": 10
  }
}

综合搜索（文件名、路径和内容）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "project planning",
    "searchIn": "all"
  }
}

高级 GitHub 搜索语法

{
  "tool": "searchFiles",
  "arguments": {
    "query": "path:*.md extension:md",
    "searchIn": "content"
  }
}

跟踪知识演变

{
  "tool": "getCommitHistory",
  "arguments": {
    "days": 30,
    "includeDiffs": true,
    "maxCommits": 10
  }
}

搜索技巧与故障排除

按名称找不到文件？

问题：搜索“OKR 2025”时，找不到名为“OKR 2025.md”的文件

解决方案：使用 searchIn: "filename" 参数：

{
  "tool": "searchFiles",
  "arguments": {
    "query": "OKR 2025",
    "searchIn": "filename"
  }
}

高级搜索技巧

1. 精确短语：使用引号进行多词搜索

   {
     "query": "\"project planning 2025\"",
     "searchIn": "content"
   }
   

2. 文件扩展名：查找特定类型的文件

   {
     "query": "path:*.md",
     "searchIn": "content"
   }
   

3. 指定目录：在文件夹中搜索

   {
     "query": "path:\"Daily Notes/\"",
     "searchIn": "content"
   }
   

项目结构

obsidian-github-mcp/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   └── github/           # GitHub API integration
│       ├── client.ts     # GitHub client implementation
│       └── types.ts      # TypeScript type definitions
├── docs/                 # Documentation
├── package.json          # Project configuration
└── tsconfig.json         # TypeScript configuration

面向开发者

如果您有兴趣为此项目做出贡献，或使用此服务开发自己的工具，请参阅开发指南。

开发命令

• pnpm install - 安装依赖
• pnpm run build - 构建项目
• pnpm run dev - 在开发模式下运行并启动检查器
• pnpm run inspector - 启动 MCP 检查器进行测试

从 mcp-private-github-search 迁移

如果您要从较早的 mcp-private-github-search 软件包迁移：

1. 在配置中更新软件包名称：

   {
     "mcpServers": {
       "obsidianGithub": {
         "command": "npx",
         "args": ["-y", "obsidian-github-mcp"]
       }
     }
   }
   

2. 功能保持不变——所有现有工具的工作方式都相同

3. 不妨了解以 Obsidian 为核心的新用例和工作流

了解更多

有关 MCP 生态系统的更多信息，请参阅：

• Model Context Protocol 文档：详细介绍 MCP 架构和设计原则
• Smithery - MCP 服务注册表：发布 MCP 服务的指南
• MCP TypeScript SDK 文档：全面的 TypeScript SDK 文档
• Obsidian：启发此工具的知识管理应用

关于 Hint Services

“未来已经到来，只是分布得并不均匀”

— William Gibson，作家

Hint Services 是一家精品咨询公司，致力于开发和拓展用户界面借助人工智能技术的方式。我们在 AI 与用户体验的交汇处构建愿景，由 Ben Hofferber 创立并领导。

我们为希望采用 AI 工具、但不想成为开发者的设计团队提供专业的 AI 工作坊。了解更多关于我们的培训和工作坊。