obsidian-mcp— agent skill

Guide the user through getting started with obsidi-mcp.

About

An Obsidian community plugin that exposes vault operations as an MCP server. Provides 28+ built-in vault tools (read, write, search, tag, link, manage notes) plus 7 CLI bridge tools for Sync history and file recovery. Supports stdio, HTTP (StreamableHTTP), and SSE transports. Other plugins can register additional tools at runtime via the Tool Provider Registry.

Prerequisites

Check that the user has the following installed/configured:

• Obsidian Desktop (not mobile — uses Node.js features)
• Node.js 18+
• npm
• Git
• For CLI bridge tools: Obsidian CLI v1.12+ (obsidian --version to verify)
• (Optional) BRAT plugin for easy installation without development setup

Setup

Walk the user through initial setup:

1. Clone the repo:

   git clone https://github.com/cameronsjo/obsidi-mcp.git
   cd obsidi-mcp

1. Install dependencies and build:

   npm install
   npm run build

1. Symlink the plugin into your Obsidian vault's plugins folder:

   ln -sfn /path/to/obsidi-mcp /path/to/your-vault/.obsidian/plugins/obsidi-mcp

1. In Obsidian, go to Settings > Community Plugins and enable Obsidi MCP.
2. Configure transport (stdio, HTTP, or SSE) in the plugin's settings tab (Settings > Obsidi MCP).

First Use

Guide the user through their first interaction with the product:

1. After enabling the plugin, open the plugin settings and confirm the server status shows as running.
2. For HTTP transport (default port 3000), test with curl:

   curl http://localhost:3000/health

1. For stdio transport, add to your Claude Code MCP config:

   {
     "mcpServers": {
       "obsidian": {
         "command": "obsidian",
         "args": ["--vault", "Your Vault Name", "--mcp"]
       }
     }
   }

1. For HTTP transport, add to your Claude Code MCP config:

   {
     "mcpServers": {
       "obsidian": {
         "url": "http://localhost:3000/mcp",
         "transport": "streamable-http"
       }
     }
   }

1. Try a basic tool call like list_notes or get_vault_stats to confirm connectivity.

Key Files

Point the user to the most important files for understanding the project:

• main.ts — Plugin entry point, onload()/onunload() lifecycle
• src/mcpServer.ts — MCP server implementation, transport setup, tool dispatch
• src/obsidianTools.ts — 28 built-in vault tool definitions and handlers
• src/cliBridge/ — CLI bridge tools for Sync history and file recovery
• src/vaultResources.ts — MCP resource subscriptions with live vault change notifications
• src/settingsTab.ts — Plugin settings UI configuration
• manifest.json — Obsidian plugin manifest (id, version, min app version)

Common Tasks

• Development with auto-rebuild:

  npm run dev

Then reload the plugin in Obsidian (Ctrl/Cmd+P > "Reload app without saving").

• Production build:

  npm run build

• Run tests:

  npm test

• Register tools from another plugin: In your plugin's onload():

  const mcp = this.app.plugins?.plugins?.['obsidi-mcp'];
  if (mcp?.registerToolProvider) {
    mcp.registerToolProvider({ id: 'my-plugin', name: 'My Plugin', tools: myTools });
  }

• Check server status: Open Obsidian Settings > Obsidi MCP. Server status is displayed at the top.