npm package: @pawells/mcp-obsidian
Description: MCP server for Obsidian vault semantic search
Author: Phillip Aaron Wells
Latest version: 1.2.0

# Obsidian MCP Server

[![GitHub Release](https://img.shields.io/github/v/release/PhillipAWells/mcp-obsidian)](https://github.com/PhillipAWells/mcp-obsidian/releases)
[![CI](https://github.com/PhillipAWells/mcp-obsidian/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/mcp-obsidian/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/PhillipAWells?style=social)](https://github.com/sponsors/PhillipAWells)

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](https://github.com/coddingtonbear/obsidian-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](https://obsidian.md) with the [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin installed and enabled
- *(Optional)* Qdrant vector database and an OpenAI API key for semantic search

### Installation

```bash
npm install -g @pawells/mcp-obsidian
```

Then configure:

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

### Running Qdrant locally (for semantic search)

```bash
docker run -p 6333:6333 qdrant/qdrant
```

### Development

```bash
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](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin
- *(For semantic search)* Qdrant and an OpenAI API key

## License

MIT — See [LICENSE](./LICENSE) for details.