Obsidian GitHub MCP

A white-label Model Context Protocol server that gives selected AI agents bounded, auditable access to propose changes to an Obsidian vault stored in GitHub.

Each agent receives its own expiring MCP bearer token. The GitHub credential remains server-side. Read and write paths, denials, protected surfaces, proposal branches, and token revocation are controlled by operator-owned YAML files.

This is an independent open-source project. It is not affiliated with or endorsed by Obsidian or GitHub.

Why use it?

Giving an agent a general GitHub token is difficult to constrain and easy to misuse. This server creates a narrower boundary:

AI agent + individual MCP token
        |
        v
identity + fixed broker
        |
        v
agent write scope AND broker publication scope
        |
        v
deny, path, frontmatter, mutability, size, and secret checks
        |
        v
server-side GitHub App token
        |
        v
proposal branch for human review

The service has no tools for deleting files, merging branches, pushing to main or master, changing repository settings, editing workflows, or exposing credentials.

Features

• Stateless MCP Streamable HTTP transport
• Unique, expiring bearer tokens stored as SHA-256 bindings
• Per-agent read, write, and deny path globs
• Separate Git broker allowlists and fixed proposal branches
• Configurable frontmatter requirements for shared or sensitive surfaces
• living, review-first, append-only, and immutable note handling
• Path-traversal prevention and file-extension/size allowlists
• Credential-shaped-content detection
• Repository-restricted GitHub App tokens with PAT fallback for local testing
• Content-free JSONL audit records
• Host/origin validation, security headers, rate limiting, and HTTP timeouts
• Docker, CI, tests, and deployment documentation

MCP tools

Requirements

• Node.js 22+
• An Obsidian vault in a GitHub repository
• A dedicated non-default proposal branch for each broker
• A GitHub App installed only on the vault repository with Contents: read and write, or a fine-grained PAT for local testing

Quick start

Install from source (the current supported path):

git clone https://github.com/YOUR_ACCOUNT/obsidian-github-mcp.git
cd obsidian-github-mcp
npm ci
cp .env.example .env
cp config/policy.example.yaml config/policy.yaml
cp config/tokens.example.yaml config/tokens.yaml
npm run token:new
npm run check
# Configure .env with your GitHub repository and token/app credentials before starting:
npm start

Configure .env (specifying your repository and either a GITHUB_TOKEN or GitHub App credentials), replace the sample policy, and put only the generated token's SHA-256 in config/tokens.yaml. Give the raw bearer token to exactly one MCP client.

To verify a checkout before configuring a running service:

npm ci
npm run check
npm run test:e2e

These checks use synthetic notes, mock GitHub responses and loopback transports. They need no GitHub or MCP credentials. Note regressions cover Unicode/path encoding, CRLF frontmatter, malformed metadata, UTF-8 size limits and append-only byte preservation. CI runs the same checks on Linux and Windows with Node.js 22 and

... View full README on GitHub