Skip to main content
Glama
README.md
# obsidian-mcp

> MCP server exposing an Obsidian vault to LLM clients (Claude, Cursor, Continue, ...).

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-1.0+-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests: 448](https://img.shields.io/badge/tests-448-brightgreen.svg)](#development)

## Why?

A Second Brain should be queryable by AI agents — **without shipping your data to a third-party API**.
This server gives any MCP-compatible client read and write access to a local Obsidian vault
via the Model Context Protocol.

**Key differentiators** (vs. existing Obsidian MCP servers):

- **Headless & filesystem-native** — no Obsidian desktop app required, container-ready
- **Structured output schemas** on every tool — LLMs know exactly what to expect
- **Vault graph analytics** — wikilink graph, orphan detection, outlink tracing
- **Vault health check** — automated quality scoring (broken links, untagged, TODOs, duplicates)
- **Policy enforcement** — write log, raw/ immutability, agent locking, and wiki-index
  upkeep enforced at the filesystem choke point, not left to client discipline
- **Ranked full-text search** — Whoosh-backed index with Lucene-style query syntax
  (fields, booleans, phrases, wildcards, fuzzy, ranges, did-you-mean)
- **AI-optimized tool descriptions** — 5-element docstring pattern with actionable error messages

## Features

- Read and Search notes (full-text, case-insensitive)
- Create, Update, Delete notes with proper YAML frontmatter
- Append to notes (upsert), patch sections under headings
- Frontmatter and tag management (get/set/delete, dedup, case-insensitive)
- Daily notes (YYYY-MM-DD format with date validation)
- Search & replace (literal + regex with capture groups)
- Backlink graph traversal (wikilinks)
- Vault structure as a JSON resource
- Path traversal protection on all entry points (vault sandbox)
- Tag extraction (frontmatter + inline tags)
- Structured output schemas for every MCP tool (29/29)
- Vault write policies: write log (per-actor shards in `.vault-write-log.d/`,
  legacy `.vault-write-log.jsonl` as fallback/opt-out), raw/ immutability,
  scope locks per agent (`.vault-lock.d/`, legacy `.vault-lock`), wiki/index.json
  upkeep, link checking. The server owns
  this bookkeeping: clients never append log lines themselves; every write tool
  takes an optional `related_to` (work-item uid) that lands in the log line
- archive_note: archive-instead-of-delete with backlink reporting
- Attachments: original files (PDF, Office, images, mails, archives) filed under
  `raw/assets/<YYYY>/<MM>/` with a companion note, SHA-256 deduplication and
  a type allow-list that always refuses executables
- Incremental Whoosh full-text index (BM25, stemmed, field queries, fuzzy,
  did-you-mean) with configurable index directory
- Vault graph analytics (nodes, edges, stats, broken links)
- Vault health scoring (0–100 with actionable issue report)

## Documentation

| Document | Description |
|---|---|
| [Build Guide](docs/BUILD_GUIDE.md) | Architecture walkthrough, code tour, extension guide, Docker/K8s deployment |
| [Semantic Search](docs/SEMANTIC_SEARCH.md) | Optional hybrid search (Whoosh + Qdrant vectors), setup and design |
| [AI Optimization Guide](docs/MCP_AI_OPTIMIZATION_GUIDE.md) | Best practices for AI-optimized MCP tool descriptions |
| [Changelog](CHANGELOG.md) | Notable changes with added, fixed, and changed items |

## Quick Start

```bash
pip install -e .

# Point at your real vault
export OBSIDIAN_VAULT_ROOT=/path/to/your/obsidian/vault

# Run (stdio transport)
obsidian-mcp
```

Or use the bundled mock vault (no config needed):

```bash
obsidian-mcp   # uses examples/mock-vault/
```

## Client Integration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "env": {
        "OBSIDIAN_VAULT_ROOT": "/path/to/your/vault"
      }
    }
  }
}
```

### Cursor

Cursor supports MCP from version 0.42+. Configure in `~/.cursor/mcp.json` (same format as Claude Desktop).

### Any other MCP client

The server runs on stdio. Register it with your client's standard MCP configuration
(command: `obsidian-mcp` or `python3 -m obsidian_mcp.server`, env: `OBSIDIAN_VAULT_ROOT`).

## Tools (29)

| Tool | Description |
|---|---|
| `read_note(path)` | Read a note (title, tags, metadata, content) |
| `search_notes(query, include_restricted?)` | Full-text search across title and body |
| `list_notes(folder?, include_restricted?)` | List notes, optionally scoped to a folder |
| `list_note_paths(folder?, include_restricted?)` | List note paths only (lightweight) |
| `create_note(path, content, tags?)` | Create a note with frontmatter |
| `update_note(path, content)` | Update body (frontmatter preserved) |
| `delete_note(path)` | Permanently delete a note |
| `append_to_note(path, content)` | Append content (create if missing) |
| `manage_frontmatter(path, action, key?, value?, values?, keys?)` | Get/set/delete one frontmatter key, or several in one write (`values` / `keys`) |
| `manage_tags(path, action, tags?)` | Add/remove/list tags |
| `patch_note(path, heading, action, content)` | Insert/prepend/replace under a heading |
| `daily_note(action, content?, date?)` | Read/append daily notes (YYYY-MM-DD.md) |
| `search_and_replace(path, find, replace, use_regex?, case_sensitive?)` | Find/replace in note body |
| `get_backlinks(title, include_restricted?)` | Find notes linking via wikilinks |
| `vault_graph(include_restricted?)` | Full vault link graph (nodes, edges, stats) |
| `find_orphans(include_restricted?)` | Notes with no incoming or outgoing wikilinks |
| `get_outlinks(path)` | Outgoing wikilinks from a note |
| `vault_health(include_restricted?)` | Health score + issue report (0–100) |
| `archive_note(path, archive_dir?)` | Move note to archive folder; report backlinks |
| `lock_scope(scope, purpose?, ttl_min?)` | Lock a folder or note for this agent (other agents' writes there are refused) |
| `refresh_lock(scope?, ttl_min?)` | Extend own active locks |
| `release_lock(scope?)` | Release own locks |
| `lock_status()` | List all active locks of all agents |
| `attach_file(filename?, content_base64? \| source_path?, description?, name?, source?, related?, keep_source?)` | File an original document under `raw/assets/` with a companion note |
| `list_attachments(query?, related?, limit?)` | List filed attachments, newest first |
| `read_attachment_info(path, verify?)` | Metadata of one attachment, optional SHA-256 check |
| `search_query(query, limit?, include_restricted?)` | Ranked Lucene-style full-text query (fields, fuzzy, ranges) |
| `rebuild_index()` | Rebuild the full-text index from all notes |
| `index_status()` | Index health: docs indexed vs. vault notes |

**Locks:** `lock_scope` writes `.vault-lock.d/<actor>.json` (one file per agent,
so file sync never merges two writers). While a lock is active, writes of other
agents whose target lies inside the scope are refused with `VAULT_LOCK`; writes
elsewhere and all reads stay possible. Locks expire on their own after `ttl_min`
(default 30, max 240). A legacy `.vault-lock` file in the vault root still locks
the whole vault for 30 minutes after its last change. `VAULT_LOCK=0` disables
both.

**Attachments:** `attach_file` takes `content_base64` (up to
`ATTACH_MAX_INLINE_MB`, default 10) or `source_path`, a file already in the vault
such as `00 Inbox/scan.pdf` (up to `ATTACH_MAX_MB`, default 100; moved unless
`keep_source`). Allowed: pdf, docx, xlsx, pptx, csv, txt, md, msg, eml, png, jpg,
jpeg, gif, webp, svg, zip, 7z, tar.gz. The content must match the extension;
executables, scripts, macro Office files and archives containing them are
refused with `ATTACHMENT_TYPE`. File and companion note are raw/ and immutable.

**Restricted folders (optional):** `OBSIDIAN_SEARCH_RESTRICTED="05 People,Private"`
hides these folders from every search, listing and graph tool (and from
`hybrid_search`) unless the call sets `include_restricted=true`. Results then
carry `restricted_hidden: true`. Reading a note by its path, or listing a
restricted folder by name, stays possible: naming it is an explicit request.
Links into a hidden folder still resolve (no false broken links), but the
graph shows only the link text, not the hidden path. Unset (default): nothing
is hidden.

**Index freshness:** on start the server reconciles the full-text index with
the files on disk in the background (notes moved or edited by file sync or the
Obsidian editor while it was not running). Processes sharing one index do this
once: a process skips if the index was reconciled within
`OBSIDIAN_INDEX_RECONCILE_MAX_AGE` seconds (default 900).
`OBSIDIAN_INDEX_RECONCILE=0` turns it off.

Optional, with `pip install 'obsidian-mcp[semantic]'` and `OBSIDIAN_SEMANTIC=1`
(see [Semantic Search](docs/SEMANTIC_SEARCH.md)):

| Tool | Description |
|---|---|
| `hybrid_search(query, limit?, folder?, include_restricted?)` | Find notes by meaning and words, fused ranking |
| `semantic_sync(max_seconds?, status_only?)` | Catch up the vector index; report its status |

### Plugins

Optional extensions are installed as Python packages with an entry point in the
group `obsidian_mcp.plugins` and enabled by name, e.g. `OBSIDIAN_PLUGINS=oversight`
(comma-separated). Nothing is loaded without the variable. A plugin's
`register(api)` can add tools (`api.add_tool(fn)`, core tool names are reserved) and
subscribe to events (`api.on(event, handler)`):

| Event | Keyword arguments |
|---|---|
| `startup` | `actor` |
| `after_write` | `path`, `action`, `layer`, `actor` |
| `policy_refusal` | `tool`, `policy`, `message`, `actor` |
| `tool_error` | `tool`, `error_type`, `message`, `actor` |

Plugins are fail-open: an error while loading or in a handler goes to stderr and
never fails a write or a tool call. They run in the server process with the
server's rights, so only enable plugins you trust. Example: the sensor of
[agent-oversight](https://github.com/nakielski/agent-oversight) reports the
server's heartbeat and every refusal or tool error as oversight signals.

## Prompts (3)

| Prompt | Arguments | Description |
|---|---|---|
| `session-start` | `project?` | Review daily notes and project context before starting work |
| `session-end` | `project?` | Document accomplishments, decisions, and open questions |
| `project-checkin` | `project` (required) | Review and update a specific project's documentation |

## Resources (1)

| URI | Description |
|---|---|
| `vault://structure` | Folder/file tree of the vault as JSON |

## Architecture

```
MCP Client  ←—MCP stdio—→  obsidian-mcp server  →  vault.py  →  Obsidian Vault
(Claude/Cursor/...)         (22 tools + 3 prompts)   (filesystem)   (*.md + YAML)
                            + 1 resource                 │
                                        policies.py ←——————┘ (write log, raw lock,
                                                        wiki index, link check)
                                        search_index.py → Whoosh index (BM25)
```

**Design decisions:**
- **Filesystem-native** instead of REST API: headless, containerizable, no app dependency
- **Path traversal protection** at all entry points (`_resolve()`, `_resolve_folder()`)
- **Singleton pattern** for Vault instance (testable via `set_vault()`)
- **Pydantic BaseModel** return types for `outputSchema` on all 22 tools

## Development

```bash
pip install -e ".[dev]"
pytest tests/       # 448 tests, all passing
```

CI runs on Python 3.10, 3.11, and 3.12 with `pytest` + `ruff`.

## License

MIT