The MCP Private GitHub Search server enables seamless integration between GitHub-hosted Obsidian vaults and AI assistants, providing tools for accessing, searching, and analyzing your knowledge base content.
Key capabilities:
Retrieve File Contents: Access specific notes or documents by their path
Enhanced File Search: Search across filenames, paths, and content using GitHub's code search syntax
Issue Search: Find GitHub issues and discussions related to your vault's repository
Commit History Analysis: Track knowledge base evolution over time, with options to filter by days, author, and include detailed diffs
Enables searching private GitHub repositories, retrieving file contents, accessing commit history with optional diffs, and searching issues based on various criteria.
Implements type-safe interactions with GitHub APIs through comprehensive TypeScript type definitions.
Utilizes Zod schemas for robust input validation of all API inputs to ensure data integrity when interacting with GitHub resources.
Obsidian GitHub MCP
A Model Context Protocol (MCP) server that connects AI assistants to GitHub repositories containing Obsidian vaults. This server enables seamless integration with your knowledge base stored on GitHub, allowing AI assistants to read, search, and analyze your Obsidian notes and documentation.
Why This Tool?
Many Obsidian users store their vaults in GitHub for backup, versioning, and collaboration. This MCP server bridges the gap between your GitHub-hosted Obsidian vault and AI assistants, enabling:
Knowledge Base Access: Retrieve specific notes and documents from your Obsidian vault
Intelligent Search: Find relevant content across your entire knowledge base
Evolution Tracking: See how your ideas and notes have developed over time
Task Integration: Connect with issues and project management workflows
Features
GitHub Repository Access: Connect to any GitHub repository containing your Obsidian vault
Type-Safe Implementation: Written in TypeScript with comprehensive type definitions
Input Validation: Robust validation for all API inputs using Zod schemas
Error Handling: Graceful error handling with informative messages
MCP Integration: Full compatibility with Claude, Cursor, Windsurf, Cline, and other MCP hosts
Available Tools
Knowledge Base Access
getFileContents: Retrieve the contents of specific notes, documents, or files from your Obsidian vault
searchFiles: Enhanced search with multiple modes:
filename
: Find files by exact filename (perfect for "OKR 2025" type searches)path
: Search anywhere in file pathscontent
: Search within file contentsall
: Comprehensive search across filenames, paths, and content
Project Management Integration
searchIssues: Search for issues and discussions related to your knowledge base projects
getCommitHistory: Track how your knowledge base has evolved over time with detailed commit history and diffs
Use Cases
For Knowledge Workers
Research Assistant: AI can access your research notes and reference materials
Writing Support: Pull relevant background information from your knowledge base
Idea Development: Track how concepts have evolved across your notes
For Developers
Documentation Access: Retrieve project documentation and technical notes
Learning Journals: Access your learning notes and code examples
Project Planning: Integrate with GitHub issues for comprehensive project management
For Students & Academics
Study Materials: Access lecture notes and study guides
Research Papers: Retrieve research notes and citations
Collaboration: Work with shared knowledge bases stored in GitHub
Installation
Using Smithery (Recommended)
The easiest way to install Obsidian GitHub MCP is using Smithery:
Manual Installation
Configuration
Add the server to your MCP settings file with the following configuration:
Required Environment Variables
GITHUB_TOKEN
: Your GitHub personal access token (create one here)GITHUB_OWNER
: The owner/organization of the GitHub repositoryGITHUB_REPO
: The name of the repository containing your Obsidian vault
GitHub Token Permissions
Your GitHub token needs the following permissions:
repo
(for private repositories) orpublic_repo
(for public repositories)read:org
(if accessing organization repositories)
Example Workflows
Accessing Your Daily Notes
Finding Files by Name (Perfect for "OKR 2025" example!)
Finding Files by Path
Finding Research on a Topic (Content Search)
Comprehensive Search (Filename, Path, and Content)
Advanced GitHub Search Syntax
Tracking Knowledge Evolution
Search Tips & Troubleshooting
Can't Find Your File by Name?
Problem: Searching for "OKR 2025" doesn't find your file named "OKR 2025.md"
Solution: Use the searchIn: "filename"
parameter:
Advanced Search Techniques
Exact Phrases: Use quotes for multi-word searches
{ "query": "\"project planning 2025\"", "searchIn": "content" }File Extensions: Find specific file types
{ "query": "path:*.md", "searchIn": "content" }Directory Specific: Search within folders
{ "query": "path:\"Daily Notes/\"", "searchIn": "content" }
Project Structure
For Developers
If you're interested in contributing to this project or developing your own tools with this server, please see the Development Guide.
Development Commands
pnpm install
- Install dependenciespnpm run build
- Build the projectpnpm run dev
- Run in development mode with inspectorpnpm run inspector
- Launch MCP inspector for testing
Migration from mcp-private-github-search
If you're migrating from the older mcp-private-github-search
package:
Update your package name in configuration:
{ "mcpServers": { "obsidianGithub": { "command": "npx", "args": ["-y", "obsidian-github-mcp"] } } }The functionality remains the same - all existing tools work identically
Consider the new Obsidian-focused use cases and workflows
Learn More
For further information on the MCP ecosystem, refer to:
Model Context Protocol Documentation: Detailed coverage of MCP architecture and design principles
Smithery - MCP Server Registry: Guidelines for publishing MCP servers
MCP TypeScript SDK Documentation: Comprehensive TypeScript SDK documentation
Obsidian: The knowledge management app that inspired this tool
About Hint Services
"The future is already here, it's just unevenly distributed"
— William Gibson, Author
Hint Services is a boutique consultancy with a mission to develop and expand how user interfaces leverage artificial intelligence technology. We architect ambition at the intersection of AI and User Experience, founded and led by Ben Hofferber.
We offer specialized AI workshops for design teams looking to embrace AI tools without becoming developers. Learn more about our training and workshops.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server that provides tools for searching private GitHub repositories, enabling access to repository files, commit history, and issues with automatic handling of rate limiting and error handling.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server for Git repository interaction and automation. This server provides tools to read, search, and manipulate Git repositories via Large Language Models.Last updated -1369,230MIT License
- AsecurityFlicenseAqualityA Model Context Protocol server that enables AI models to interact with GitHub's API, allowing for repository creation and management with descriptions, topics, and website URLs through natural language commands.Last updated -
- -securityFlicense-qualityA Model Context Protocol server that supports remote connections and authenticates users via GitHub OAuth, allowing them to access tools based on their GitHub identity.Last updated -
- -securityFlicense-qualityModel Context Protocol server that enables interaction with GitHub repositories, issues, pull requests, and search functionality through natural language.Last updated -1