MCP Tools for Obsidian

The plugin implements several security layers to protect vault data:

• Binary Integrity: All server binaries are signed and include SLSA provenance.
• Encrypted Communication: All communication is encrypted using the Local REST API's TLS.
• Secure Key Management: API keys are stored using platform-specific secure methods.
• Principle of Least Privilege: The server runs with only the minimal required permissions.

MCP Tools for Obsidian works by creating a secure bridge between your vault and AI applications using two main components:

1. Obsidian Plugin: Adds MCP capabilities directly to your Obsidian vault.
2. Local MCP Server: A secure bridge that handles communication with AI applications (like Claude Desktop).

Security Model: The MCP server acts as a gatekeeper. AI applications never have direct access to your vault files; they interact only with the server's secure API, which requires explicit permission and uses your Local REST API key to perform actions like reading notes or executing templates.

The Obsidian plugin is organized into self-contained feature modules located in src/features/. This architecture ensures that each feature is decoupled, allowing them to initialize independently, manage their own dependencies, and continue running even if other features fail.

Each feature module follows a standardized structure:

• components/: UI components specific to the feature.
• services/: Business logic.
• types.ts: Feature-specific TypeScript types.
• utils.ts: Feature-specific utility functions.
• constants.ts: Feature-specific constants.
• index.ts: The public API, which must export a setup function.

// Example feature structure
src/features/
├── core/
├── mcp-server-install/
├── mcp-server-prompts/
└── smart-search/

This project is a Bun-based monorepo. To set up a development environment:

1. Install Dependencies:

   bun install

2. Build All Packages:

   bun run build

3. Run Development Mode:

   bun run dev

Workspace Structure:

• packages/mcp-server/: Server implementation.
• packages/obsidian-plugin/: Obsidian plugin.
• packages/shared/: Shared utilities and types.

The MCP server binaries are published with SLSA Provenance attestations. You can verify the integrity and origin of the binary using the GitHub CLI to ensure it was built by the official repository's GitHub Actions workflows.

1. Install the GitHub CLI (gh) via Homebrew (macOS), Scoop (Windows), or apt (Linux).
2. Run the following command against the binary path or URL:

gh attestation verify --owner jacksteamdev <binary path or URL>

Before installing, ensure you meet the following requirements:

Required

• Obsidian: v1.7.7 or higher.
• Claude Desktop: Installed and configured.
• Local REST API Plugin: Must be installed and configured with an API key (this is required for Vault Access).

Recommended

• Templater Plugin: For enhanced template integration functionality.
• Smart Connections Plugin: For semantic search capabilities.

To set up the development environment for the shared package, use bun to install dependencies and execute the entry point.

# Install dependencies
bun install

# Run the package
bun run index.ts

To completely remove the MCP server and its integration, use the Uninstall button in the plugin settings. This performs the following cleanup actions:

1. Removes the MCP server executable from your vault.
2. Removes the obsidian-mcp-tools entry from your Claude Desktop configuration file.
3. Clears stored plugin data.

To ensure type-safe access to feature-specific settings, use TypeScript module augmentation to extend the McpToolsPluginSettings interface. This allows you to add new configuration keys that are automatically recognized when calling McpToolsPlugin.loadData() and McpToolsPlugin.saveData().

// packages/obsidian-plugin/src/features/some-feature/types.ts
declare module "obsidian" {
  interface McpToolsPluginSettings {
    featureName?: {
      setting1?: string;
      setting2?: boolean;
    };
  }
}

The plugin is part of a monorepo and uses bun for development tasks. Use the following commands to manage the development lifecycle:

• Install dependencies: bun install
• Start development build (watch mode): bun run dev
• Create a production build: bun run build
• Link plugin to a vault for testing: bun run link <path-to-vault-config-file>

# Install dependencies
bun install

# Start development build with watch mode
bun run dev

# Create a production build
bun run build

# Link plugin to your vault for testing
bun run link <path-to-vault-config-file>

Server binaries are published with SLSA Provenance attestations to ensure security. You can verify that a binary was built from this repository and complies with SLSA Level 3 using the GitHub CLI (gh).

gh attestation verify --owner jacksteamdev <binary>