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: Search for notes and documents within your vault using GitHub's powerful search syntax

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:

# 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

Manual Installation

npm install obsidian-github-mcp

Configuration

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

Required Environment Variables

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

GitHub Token Permissions

Your GitHub token needs the following permissions:

repo (for private repositories) or public_repo (for public repositories)
read:org (if accessing organization repositories)

Example Workflows

Accessing Your Daily Notes

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

Finding Research on a Topic

{
  "tool": "searchFiles",
  "arguments": {
    "query": "machine learning algorithms in:path",
    "perPage": 10
  }
}

Tracking Knowledge Evolution

{
  "tool": "getCommitHistory",
  "arguments": {
    "days": 30,
    "includeDiffs": true,
    "maxCommits": 10
  }
}

Project Structure

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

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 dependencies
pnpm run build - Build the project
pnpm run dev - Run in development mode with inspector
pnpm 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.

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

Tools

A Model Context Protocol server that connects AI assistants to GitHub repositories containing Obsidian vaults, enabling them to read, search, and analyze notes and documentation stored on GitHub.

Related Resources

Reddit Discussion about this server

Related MCP Servers

MCP GitHub Repository Server
loglmhq
-
security
A
license
-
quality
A server that allows AI assistants to browse and read files from specified GitHub repositories, providing access to repository contents via the Model Context Protocol.
Last updated -
3
JavaScript
MIT License
GitHub MCP Server
PoliTwit1984
A
security
F
license
A
quality
A 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 -
1
JavaScript
Obsidian MCP
takuya0206
-
security
A
license
-
quality
A Model Context Protocol server that enables AI assistants to read, write, and manipulate notes in your Obsidian vault through a standardized interface.
Last updated -
598
TypeScript
ISC License
GitHub MCP Server
renantrendt
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to perform GitHub operations including repository management, file operations, issue tracking, and pull request creation.
Last updated -
1
TypeScript

View all related MCP servers

Obsidian GitHub MCP