ObsidianKB MCP Server

Git-backed MCP server for creating and maintaining an Obsidian-style markdown knowledge base.

Implemented Scope

• Full MCP toolset: kb_create, kb_search, kb_get, kb_update, kb_list, kb_delete, kb_sync
• Seven skills and templates: bug report, API doc, component doc, changelog, ADR, guide, runbook
• Frontmatter-aware markdown read/write and path safety checks
• MiniSearch indexing with filters and field boosting
• Git pull/commit/push workflow
• obsidian-kb-mcp init [path] scaffold command
• CI workflow (.github/workflows/validate.yml)

Requirements

• Node.js 20+
• Git installed and configured

Installation

npm install
npm run build

Usage

Run as MCP server (stdio transport):

node dist/index.js

Initialize a vault scaffold:

node dist/index.js init ./my-kb

Configuration

Create obsidian-kb.config.json in the runtime working directory:

{
  "vault_path": "/absolute/path/to/obsidian-kb",
  "remote": "origin",
  "default_branch": "main",
  "auto_pull_before_read": true,
  "auto_push_after_write": true,
  "default_author": "your-github-username",
  "commit_prefix": "[kb]",
  "search": {
    "boost": {
      "title": 3,
      "tags": 2,
      "body": 1
    },
    "fuzzy": 0.2
  }
}

Environment overrides:

• OBSIDIAN_KB_VAULT_PATH
• OBSIDIAN_KB_AUTHOR
• OBSIDIAN_KB_AUTO_PUSH

Scripts

• npm run dev - run server in tsx
• npm run build - bundle with tsup
• npm run lint - biome check
• npm run format - biome format
• npm test - vitest

MCP client example (Cursor)

{
  "mcpServers": {
    "obsidian-kb": {
      "command": "node",
      "args": ["/absolute/path/to/obsidianKB/dist/index.js"],
      "env": {
        "OBSIDIAN_KB_VAULT_PATH": "/absolute/path/to/obsidian-vault",
        "OBSIDIAN_KB_AUTHOR": "your-github-username"
      }
    }
  }
}