Obsidian GitHub MCP

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:

- 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

- 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

- 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 paths
- content: Search within file contents
- all: Comprehensive search across filenames, paths, and content

- 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

- 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

- 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

- Study Materials: Access lecture notes and study guides
- Research Papers: Retrieve research notes and citations
- Collaboration: Work with shared knowledge bases stored in GitHub

The 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

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 repository
- GITHUB_REPO: The name of the repository containing your Obsidian vault

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

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

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

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

{ "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 theDevelopment Guide.

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

- 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

We offer specialized AI workshops for design teams looking to embrace AI tools without becoming developers.Learn more about our training and workshops.

Access and manage your library on Apple Books.