Obsidian GitHub MCP

](https://smithery.ai/server/@Hint-Services/obsidian-github-mcp) ](https://www.npmjs.com/package/obsidian-github-mcp)

Obsidian GitHub MCP（注：这里的“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主机完全兼容

可用工具

知识库访问

• 获取文件内容从您的Obsidian知识库中检索特定笔记、文档或文件的内容
• 搜索文件增强搜索功能，支持多种模式：

- filename通过精确文件名查找文件（非常适合“2025年目标与关键成果（OKR）”类型的搜索） - path在文件路径中的任何位置进行搜索 - content在文件内容中搜索 - all在文件名、路径和内容中进行全面搜索

项目管理整合

• 搜索问题搜索与您的知识库项目相关的问题和讨论
• 获取提交历史跟踪您的知识库随时间的演变情况，查看详细的提交历史和差异

用例

针对知识工作者

• 研究助理人工智能可以访问您的研究笔记和参考资料
• 写作支持从你的知识库中提取相关的背景信息
• 创意开发追踪你的笔记中概念是如何演变的

对于开发者

• 文档访问获取项目文档和技术说明
• 学习日志访问您的学习笔记和代码示例
• 项目规划与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_OWNERGitHub仓库的所有者/组织
• GITHUB_REPO包含您Obsidian知识库的仓库名称

GitHub 令牌权限

您的GitHub令牌需要以下权限：

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

示例工作流程

访问您的每日笔记

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

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

{
  "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"
   }

1. 文件扩展名查找特定文件类型

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

1. 特定目录在文件夹内搜索

   {
     "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"]
       }
     }
   }

1. 功能保持不变——所有现有工具均按原样工作

1. 考虑新的以Obsidian为中心的用例和工作流程

了解更多

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

• 模型上下文协议文档详细阐述MCP架构及设计原则
• Smithery - MCP 服务器注册表发布MCP服务器的指南
• MCP TypeScript SDK 文档全面的TypeScript SDK文档
• 黑曜石激发开发此工具的知识管理应用程序

关于提示服务

“未来已经到来，只是分布不均” — 威廉·吉布森，作家

Hint Services是一家精品咨询公司，其使命是开发并拓展用户界面如何利用人工智能技术的潜力。我们致力于在人工智能与用户体验的交汇点上构建宏伟蓝图，公司由Ben Hofferber创立并领导。

我们为希望采用AI工具但又不想成为开发者的团队提供专门的AI工作坊。 了解更多关于我们的培训和研讨会信息。