Connects AI assistants to Obsidian vaults stored in GitHub repositories, enabling them to read, search, and analyze your notes and documentation.
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.
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:
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 contentThe easiest way to install Obsidian GitHub MCP is using 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
Add the server to your MCP settings file with the following configuration:
{
"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
: 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 vaultYour GitHub token needs the following permissions:
repo
(for private repositories) or public_repo
(for public repositories)read:org
(if accessing organization repositories){
"tool": "getFileContents",
"arguments": {
"filePath": "Daily Notes/2024-01-15.md"
}
}
{
"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"
}
}
{
"tool": "searchFiles",
"arguments": {
"query": "path:*.md extension:md",
"searchIn": "content"
}
}
{
"tool": "getCommitHistory",
"arguments": {
"days": 30,
"includeDiffs": true,
"maxCommits": 10
}
}
Problem: Searching for "OKR 2025" doesn't find your file named "OKR 2025.md"
Solution: Use the searchIn: "filename"
parameter:
{
"tool": "searchFiles",
"arguments": {
"query": "OKR 2025",
"searchIn": "filename"
}
}
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"
}
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
If you're interested in contributing to this project or developing your own tools with this server, please see the Development Guide.
pnpm install
- Install dependenciespnpm run build
- Build the projectpnpm run dev
- Run in development mode with inspectorpnpm run inspector
- Launch MCP inspector for testingIf 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
For further information on the MCP ecosystem, refer to:
"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.
AI-powered GitHub project management with complete requirements traceability.
A server for GitHub project management with advanced resource management, capacity planning, and workload optimization capabilities.
An MCP server for interacting with and automating Git repositories using Large Language Models.
Integrates with GitHub APIs for advanced automation and interaction, supporting both remote and local deployments.
Manage GitHub repositories using a personal access token via CLI or environment variables.
Interact with the GitHub API for file operations, repository management, and search.
Integrates with GitHub, allowing LLMs to interact with repositories, issues, and pull requests via the GitHub API.
Interact with GitHub repositories, including issues, pull requests, commits, releases, and actions.
Gitee API integration, repository, issue, and pull request management, and more.
An MCP server for integrating with and managing Subversion (SVN) repositories, enabling AI agents to perform version control tasks.