obsidian-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Obsidian MCP Server is an Obsidian desktop plugin that runs a local Model Context Protocol (MCP) server inside Obsidian. External AI tools (Claude Desktop, Cursor, CLI agents) connect via Streamable HTTP to read vault content and perform actions. The plugin is desktop-only. Bearer token authentication is enabled by default but can be disabled in settings.

Build & Development Commands

pnpm run dev       # Watch mode (esbuild, outputs main.js)
pnpm run build     # Production build (esbuild, outputs main.js)
pnpm run lint      # ESLint on src/**/*.ts
pnpm test          # Jest tests

The build output is main.js in the project root (not a dist/ folder). This is the file Obsidian loads as the plugin entry point.

Architecture

Modular plugin — code is organized across focused modules in src/. Key classes and modules:

1. McpPlugin (src/main.ts) — Entry point. Manages plugin lifecycle, settings + stats persistence, Express server, and MCP tool registration.
2. SecurityManager (src/security.ts) — Enforces access control via a blacklist system. Two rule types:
   • Path rules: prefix-match on vault paths (e.g., Secret/ blocks all files under that folder)
   • Tag rules: prefix-match on tags (e.g., #secret blocks files with that tag, including nested tags like #secret/nested). Tags are read from both inline tags and frontmatter.
3. McpSettingTab (src/settings.ts) — Settings UI for port, auth token, blacklist rules, and tool usage statistics display.
4. McpHttpServer (src/server.ts) — Express server with Streamable HTTP transport, session management, and timing-safe auth.
5. StatsTracker (src/stats.ts) — Tool usage statistics with debounced persistence. Wraps tool handlers via track() to auto-record total/success/fail counts.
6. Tools (src/tools/) — Each tool in its own file, registered via src/tools/index.ts.