Obsidian MCP Server

Model Context Protocol (MCP) server for Obsidian vault interaction and semantic search. Connects Claude Code (or any MCP client) to a running Obsidian instance via the Local REST API plugin, with optional AI-powered semantic search backed by Qdrant and OpenAI.

Features

• Note CRUD — Read, create, update, append, patch, delete, and rename notes
• Vault browsing — List files and folders in the vault
• Intelligent search — Hybrid text + semantic (AI-powered) search, phrase search, Dataview DQL, and JsonLogic queries with rich filtering by path, tag, metadata, and date
• Semantic indexing — Background indexing of the vault using OpenAI embeddings stored in Qdrant; real-time file watcher keeps the index current
• Metadata tools — Query, set, and delete YAML frontmatter fields; find notes by metadata value
• Periodic notes — Read, create, and append to daily/weekly/monthly notes; retrieve notes for a specific date
• Command execution — List and execute Obsidian commands; open notes in the Obsidian UI

Quick Start

Prerequisites

• Node.js >= 24.0.0
• Obsidian with the Local REST API plugin installed and enabled
• (Optional) Qdrant vector database and an OpenAI API key for semantic search

Installation

npm install -g @pawells/mcp-obsidian

Then configure:

cp .env.example .env
# Edit .env — set at minimum OBSIDIAN_API_KEY

Running Qdrant locally (for semantic search)

docker run -p 6333:6333 qdrant/qdrant

Development

yarn build          # Compile TypeScript → ./build/
yarn start          # Run the server
yarn dev            # Build + run
yarn watch          # TypeScript watch mode
yarn typecheck      # Type check without building
yarn lint           # ESLint src/
yarn lint:fix       # ESLint with auto-fix
yarn test           # Run tests
yarn test:ui        # Open interactive Vitest UI
yarn test:coverage  # Run tests with coverage report

Configuration

| Variable | Default | Description | |----------|---------|-------------| | OBSIDIAN_API_KEY | (required) | API key from the Obsidian Local REST API plugin | | OBSIDIAN_BASE_URL | https://127.0.0.1:27123 | Base URL of the Obsidian Local REST API | | QDRANT_URL | http://localhost:6333 | Qdrant server URL (required for semantic search) | | QDRANT_API_KEY | (optional) | API key for Qdrant Cloud | | QDRANT_COLLECTION_NAME | obsidian-semantic-index | Qdrant collection name | | OPENAI_API_KEY | (optional) | OpenAI API key — required for semantic search indexing | | LOG_LEVEL | info | Log level: debug, info, warn, error |

Semantic search is initialized only when both QDRANT_URL and OPENAI_API_KEY are set. All other tools work without them.

Available MCP Tools

File Tools

| Tool | Description | |------|-------------| | read_note | Read the content of a note (markdown or JSON) | | create_note | Create a new note at a given path | | update_note | Full replacement or diff-style editing of an existing note | | append_to_note | Append content to a note | | patch_note | Apply a structured patch to a note | | delete_note | Delete a note from the vault | | rename_note | Rename or move a note | | list_vault | List files and folders in the vault |

Search Tools

| Tool | Description | |------|-------------| | search | Intelligent search across the vault. Runs text and semantic searches in parallel, merges results. Supports hybrid, phrase, semantic, and text modes; Dataview DQL and JsonLogic queries; filtering by path, tag, metadata, and date. |

Command Tools

| Tool | Description | |------|-------------| | list_commands | List all available Obsidian commands | | execute_command | Execute an Obsidian command by ID | | open_note | Open a note in the Obsidian UI |

Metadata Tools

| Tool | Description | |------|-------------| | query_metadata | Query YAML frontmatter from one or more notes (by path, array of paths, or glob) | | list_files_by_metadata | Find notes with a specific metadata field value | | set_metadata | Set a YAML frontmatter field on a note | | delete_metadata | Delete a YAML frontmatter field from a note |

Periodic Note Tools

| Tool | Description | |------|-------------| | get_periodic_note | Get the note for the current period (day, week, month, etc.) | | create_periodic_note | Create or replace a periodic note for the current period | | append_periodic_note | Append content to the current periodic note (creates if not exists) | | get_date_note | Get a periodic note for a specific date |

Architecture

MCP Client (Claude Code)
       ↓  stdio transport
MCP Server (src/index.ts)
       ↓
Tool Handlers (src/tools/)
  ├── file-tools.ts       — Note CRUD and vault listing
  ├── search-tools.ts     — Unified search (text + semantic + Dataview/JsonLogic)
  ├── command-tools.ts    — Obsidian command execution
  ├── metadata-tools.ts   — YAML frontmatter operations
  └── periodic-tools.ts   — Daily/weekly/monthly note operations
       ↓
Services:
  ├── ObsidianClient      — HTTP client for the Local REST API plugin
  ├── SemanticIndexer     — Background vault indexer using OpenAI + Qdrant + chokidar file watcher
  ├── SearchService       — Merges text search and semantic search results
  └── QdrantClientWrapper — Qdrant vector DB operations

Requirements

• Node.js >= 24.0.0
• Obsidian with Local REST API plugin
• (For semantic search) Qdrant and an OpenAI API key

License

MIT — See LICENSE for details.