diagnoseSearch
Diagnose search functionality and repository configuration for your Obsidian vault on GitHub. Verifies repository connectivity, search capabilities, and checks if repository size is within GitHub's indexing limits.
LABSCO SUMMARY
If your vault already lives in GitHub, this reads it where it is — no sync, no local copy, no running app.
The searchIn parameter is the thing to learn first: a content search for 'OKR 2025' will not find a file called OKR 2025.md, so pass searchIn: filename when you are after a note by name. Because everything rides on GitHub's search index, a large repository can fall outside what GitHub indexes — run diagnoseSearch when results come back empty and the query looked right.
What it is
A read-only bridge between an AI client and a GitHub-hosted Obsidian vault. Everything goes through the GitHub API, so nothing has to be checked out locally and Obsidian never has to be open.
What you get
- getFileContents to read one note, document or file from the vault by path
- searchFiles with a searchIn mode that decides where to look: filename for exact file names, path for anywhere in the path, content for the text inside, or all for every one of them — with paging and GitHub's own search syntax available
- searchIssues across the repository's issues and discussions, for vaults where tasks are tracked alongside notes
- getCommitHistory over a window of days with an author filter, a commit cap and optional diffs, so you can watch a note develop
- diagnoseSearch to check repository connectivity and whether the repository is within GitHub's indexing limits
Requirements
A GitHub personal access token in GITHUB_TOKEN, plus GITHUB_OWNER and GITHUB_REPO naming the repository the vault lives in. The token needs repo for a private repository or public_repo for a public one, and read:org when the repository belongs to an organisation. Run it over stdio with npx -y obsidian-github-mcp.
Setup effort
One command plus a key — npm install obsidian-github-mcp, then supply credentials
USE CASES
01
Reading a specific note you already know the path of
Fetch the file's contents directly rather than searching for it.
02
Finding a note by its name
Search with the filename mode so the title is what gets matched.
03
Finding everything you have written on a topic
Search inside file contents, paging through the matches.
04
Seeing how an idea developed
Pull the commit history for a window of days, with diffs, and read the changes.
05
Picking up the tasks tracked alongside the notes
Search the repository's issues and discussions from the same place.
06
Working out why a search returned nothing
Check connectivity and whether the repository is inside GitHub's indexing limits.
5 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
getCommitHistory
Track the evolution of your Obsidian vault knowledge base by retrieving commit history from GitHub. See how your notes and ideas have developed over time with detailed diffs.
getFileContents
Retrieve the contents of a specific note, document, or file from your Obsidian vault stored in GitHub. Perfect for accessing your knowledge base content.
searchFiles
Search for notes, documents, and files within your Obsidian vault on GitHub. Find specific knowledge base content using GitHub's powerful search syntax. Supports searching in filenames, paths, and content.
searchIssues
Search for issues and discussions in your Obsidian vault repository. Great for tracking tasks, project management, and collaborative knowledge work.
BEFORE YOU INSTALL
What to know first
Tools you get
5 tools when we connected. The fifth tool, diagnoseSearch, is undocumented and helps work out why a search returned nothing. searchFiles is one tool with filename, path, content and all modes.
Requires
- npx on PATH
- GITHUB_TOKEN in your environment
Where it runs
All 4 documented clients run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 5 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install obsidian-github-mcpMCP Clients
Claude Desktop, Cursor, Windsurf, Cline
JSON
{
"mcpServers": {
"obsidianGithub": {
"command": "npx",
"args": [
"-y",
"obsidian-github-mcp"
],
"env": {
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
"GITHUB_OWNER": "<YOUR_GITHUB_OWNER>",
"GITHUB_REPO": "<YOUR_GITHUB_REPO>"
}
}
}
}
