How do I install Obsidian GitHub MCP?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Obsidian GitHub MCP need an API key?

The publisher lists these environment variables: VAULT_MCP_PORT, VAULT_MCP_GITHUB_OWNER, VAULT_MCP_GITHUB_REPO, VAULT_MCP_POLICY_FILE, VAULT_MCP_TOKEN_FILE, GITHUB_TOKEN, GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY_FILE.

What transport does Obsidian GitHub MCP use?

Obsidian GitHub MCP runs locally over stdio.

When was Obsidian GitHub MCP last checked?

Last checked 2026-11-09. A permissioned MCP gateway for agent proposals to a Git-backed Obsidian vault.

Obsidian GitHub MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @sarutobi-sasuke/[email protected]

Credentials from the publisher

VAULT_MCP_PORT — Loopback HTTP listening port.
VAULT_MCP_GITHUB_OWNER — Owner of the operator-authorised vault repository.
VAULT_MCP_GITHUB_REPO — Operator-authorised vault repository name.
VAULT_MCP_POLICY_FILE — Absolute path to the operator-provisioned policy YAML.
VAULT_MCP_TOKEN_FILE — Absolute path to the operator-provisioned client-token YAML.
GITHUB_TOKEN — Required for the token-based quickstart. Alternatively configure all three GitHub App variables documented in README.
GITHUB_APP_ID — GitHub App alternative: set all three App variables instead of GITHUB_TOKEN.
GITHUB_APP_INSTALLATION_ID — GitHub App installation ID, required with GITHUB_APP_ID.
GITHUB_APP_PRIVATE_KEY_FILE — Absolute path to the operator-provisioned App private key; required with GITHUB_APP_ID.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1VAULT_MCP_PORT=<value> VAULT_MCP_GITHUB_OWNER=<value> VAULT_MCP_GITHUB_REPO=<value> VAULT_MCP_POLICY_FILE=<value> VAULT_MCP_TOKEN_FILE=<value> GITHUB_TOKEN=<secret> GITHUB_APP_ID=<value> GITHUB_APP_INSTALLATION_ID=<value> GITHUB_APP_PRIVATE_KEY_FILE=<secret> claude mcp add io.github.sarutobisasuke8-obsidian-github-mcp -- npx -y @sarutobi-sasuke/obsidian-github-mcp@0.1.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.sarutobisasuke8-obsidian-github-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@sarutobi-sasuke/[email protected]"8      ],9      "env": {10        "VAULT_MCP_PORT": "<value>",11        "VAULT_MCP_GITHUB_OWNER": "<value>",12        "VAULT_MCP_GITHUB_REPO": "<value>",13        "VAULT_MCP_POLICY_FILE": "<value>",14        "VAULT_MCP_TOKEN_FILE": "<value>",15        "GITHUB_TOKEN": "<secret>",16        "GITHUB_APP_ID": "<value>",17        "GITHUB_APP_INSTALLATION_ID": "<value>",18        "GITHUB_APP_PRIVATE_KEY_FILE": "<secret>"19      }20    }21  }22}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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

Tool	Purpose
`vault_whoami`	Show the authenticated identity, broker, branch, and policy scopes.
`vault_list_allowed_paths`	Explain effective read/write/deny boundaries.
`vault_explain_access`	Dry run a single path. Report whether read, list, or write would be permitted and which policy rule decides it. No GitHub call.
`vault_list_files`	List an authorised directory while filtering denied children.
`vault_read_file`	Read an authorised UTF-8 vault file.
`vault_create_file`	Create a file on the identity's fixed proposal branch.
`vault_update_file`	Update a permitted file while respecting mutability.
`vault_append_file`	Append while preserving all existing bytes.

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 24. The 8 tools listed above are the current server surface; tests do not publish proposals to a real vault.

Once v0.1.0 is published to npm, a global install will also be available:

# Available once v0.1.0 is published (not yet on the npm registry).
npm install -g @sarutobi-sasuke/obsidian-github-mcp

The default endpoints are:

GET  http://127.0.0.1:3210/healthz
POST http://127.0.0.1:3210/mcp

MCP clients must send:

Authorization: Bearer vault_<generated-token>

Permission model

The effective write scope is the intersection of the agent grant and its broker:

policy_version: 1
authority: operator-only

agents:
  - id: example-writer
    name: Example Writer
    role: bounded knowledge worker
    disclosure_ceiling: internal
    entry_reads: [README.md]
    read: [Knowledge/**, Workspace/**]
    write: [Workspace/Shared/**, Workspace/Example Writer/**]
    deny: [Private/**, People/**, .obsidian/**]

git_brokers:
  - broker: example-writer
    branch: agent/example-writer
    allow: [Workspace/Shared/**, Workspace/Example Writer/**]

never_versioned: [Private/**, People/**, .obsidian/**, secrets/**]

surface_rules:
  - path: Workspace/Shared/**
    required_frontmatter:
      disclosure: public-safe

An auth binding then maps one token hash to that identity and broker. The binding cannot grant paths that the policy does not grant.

See Permissions documentation for provisioning and revocation.

GitHub authentication

Production deployments should use a GitHub App installed only on the vault repository. Configure:

GITHUB_APP_ID=123456
GITHUB_APP_INSTALLATION_ID=12345678
GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/vault-mcp.pem

The server creates short-lived installation tokens restricted again to the configured repository and contents: write. A repository-scoped GITHUB_TOKEN is supported as a local-development fallback.

Deployment

The included container runs as a non-root user with a read-only root filesystem. Put TLS, a private overlay network, or an authenticated gateway in front of the service before making it remotely reachable.

See Deployment guide.

Verification

npm run check
npm audit --audit-level=high

Tests cover policy parsing, write-scope intersection, deny precedence, traversal attempts, frontmatter rules, mutability, secret detection, token bindings, and fixed-branch GitHub writes.

Run npm run test:e2e for a clean tarball installation and real MCP HTTP client proof against a test-only GitHub substitute. It exercises proposal writes, denied paths/content, immutable and append-only notes, stale-write conflicts, invalid policy reloads, live token revocation and content-free audit records. CI runs this proof on Windows/Linux with Node 22/24, and the release workflow requires it.

Policy and token files reject unknown keys. Only policy_version: 1 and authority: operator-only are supported. Correct misspelt fields or remove unsupported metadata before upgrading; silently ignored restrictions are no longer accepted. Release evidence and remaining gates.

The draft MCP Registry npm entry describes a self-hosted Streamable HTTP process, not a stdio server. A compatible client starts the process with the declared environment and connects to http://127.0.0.1:{VAULT_MCP_PORT}/mcp (port 3210 by default). Supply the existing policy and token-file paths plus the repository owner/name. For GitHub access, use either GITHUB_TOKEN or all three documented GitHub App variables. The manifest cannot express that alternative group; runtime configuration validates it. The process does not create credentials, provision a hosted endpoint or bypass its existing bearer-token checks. The namespace preserves the exact GitHub owner spelling. prepublishOnly includes the registry/package gate; no login or publication is performed by it.

Security

Read Security policy before deployment. Report suspected vulnerabilities privately rather than opening a public issue with exploit details.

License

Apache-2.0. See Apache-2.0 License.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Obsidian GitHub MCP?

Does Obsidian GitHub MCP need an API key?

What transport does Obsidian GitHub MCP use?

When was Obsidian GitHub MCP last checked?

Documentation

Obsidian GitHub MCP

Why use it?

Features

MCP tools

Requirements

Quick start

Permission model

GitHub authentication

Deployment

Verification

Security

License