Obsidian Vault MCP

@dan_cmos/obsidian-vault-mcp is an MCP server for an authenticated local Obsidian bridge.

It preserves the existing obsidian_* tool contract and OBSIDIAN_BRIDGE_* environment variables while allowing each consuming project to scope itself to a stable root inside a shared vault.

Security Model

• the MCP only knows a bridge URL, a bearer token, and an optional project root
• no absolute vault path is stored in git
• the bridge token is generated and stored inside the Obsidian plugin
• the bridge host is configurable for local Windows and WSL setups

Install

From npm:

npm install -g @dan_cmos/obsidian-vault-mcp

The package currently targets the npm scope @dan_cmos.

Or run without a global install from a compatible MCP client:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["-y", "@dan_cmos/obsidian-vault-mcp"],
      "env": {
        "OBSIDIAN_BRIDGE_BASE_URL": "http://127.0.0.1:27124",
        "OBSIDIAN_BRIDGE_TOKEN": "<copied-from-plugin>",
        "OBSIDIAN_BRIDGE_PROJECT_ROOT": "Central Vault/Example Project"
      }
    }
  }
}

For local development from this repository:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": ["/absolute/path/to/apps/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_BRIDGE_BASE_URL": "http://127.0.0.1:27124",
        "OBSIDIAN_BRIDGE_TOKEN": "<copied-from-plugin>",
        "OBSIDIAN_BRIDGE_PROJECT_ROOT": "Central Vault/Example Project"
      }
    }
  }
}

Required Local Environment

Default local setup:

OBSIDIAN_BRIDGE_BASE_URL=http://127.0.0.1:27124
OBSIDIAN_BRIDGE_TOKEN=<copied-from-plugin>
OBSIDIAN_BRIDGE_PROJECT_ROOT=Central Vault/Example Project

Windows Obsidian plus WSL MCP client:

OBSIDIAN_BRIDGE_BASE_URL=http://<windows-wsl-host-ip>:27124
OBSIDIAN_BRIDGE_TOKEN=<copied-from-plugin>
OBSIDIAN_BRIDGE_PROJECT_ROOT=Central Vault/Example Project

OBSIDIAN_BRIDGE_PROJECT_ROOT is optional. When set, the MCP automatically scopes:

• obsidian_list_notes
• obsidian_search_notes
• obsidian_upsert_note
• obsidian_patch_heading
• obsidian_patch_frontmatter
• obsidian_read_note
• obsidian_resolve_note

Compatibility notes:

• OBSIDIAN_PROJECT_ROOT is accepted as an alias for OBSIDIAN_BRIDGE_PROJECT_ROOT
• the legacy bin alias multify-obsidian-mcp remains available
• obsidian_* tool names are unchanged

Tools

• obsidian_health
• obsidian_list_notes
• obsidian_resolve_note
• obsidian_read_note
• obsidian_search_notes
• obsidian_upsert_note
• obsidian_patch_heading
• obsidian_patch_frontmatter

Development

npm install --package-lock=false
npm test
npm run check
npm run build

Semantic Versioning

This package uses semantic versioning for the MCP surface:

• major: breaking changes to MCP tool names, environment variables, output contracts, or runtime requirements
• minor: new backward-compatible MCP capabilities
• patch: backward-compatible fixes, packaging fixes, and security fixes
• prereleases: use prepatch, preminor, premajor, or prerelease when you want an -rc.N style publish first

Version management commands:

npm run version:patch
npm run version:minor
npm run version:major
npm run version:prepatch
npm run version:preminor
npm run version:premajor
npm run version:prerelease

Each command updates:

• package.json
• src/version.ts
• CHANGELOG.md

Release

This package is released from the monorepo via .github/workflows/release-mcp.yml.

Before cutting a release:

npm run version:patch   # or minor / major / prerelease

Then review CHANGELOG.md, run the repo release gate, and push the matching mcp-vx.y.z tag.