Obsidian Knowledge Management MCP Server

A local MCP (Model Context Protocol) server that provides stateless I/O access to Obsidian vaults. This server enables LLMs to read, analyze, and manage Obsidian markdown files, YAML frontmatter, and wikilinks.

Key Features

• Stateless I/O Layer: Pure data access and atomic operations - no semantic analysis

• 35+ MCP Tools: Comprehensive vault management across 5 categories

• Frontmatter Management: Parse, update, and validate YAML metadata

• Wikilink Operations: Extract, analyze, and manipulate [[wikilinks]]

• Graph Operations: Build link graphs, find backlinks, identify orphan notes

• Full-Text Search: Literal and regex pattern matching across vault

• Security: Path validation prevents directory traversal attacks

Installation

Configuration

Create a .env file based on .env.example:

Or set environment variables when running:

Usage

Running the Server

The server uses stdio transport for MCP communication:

Claude Desktop Integration

Add to your Claude Desktop MCP configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Available Tools (Phase 1 - Navigation)

1. list_notes

List all notes with optional filtering.

Arguments:

• folder (optional): Filter by folder path

• tags (optional): Array of tags (note must have all)

• dateRange (optional): { start, end } in ISO format

• offset (optional): Skip N notes for pagination

• limit (optional): Return max N notes

Example:

Returns: Array of NoteMetadata with path, title, created date, tags, modified date, size.

2. read_note

Read a note with full metadata.

Arguments:

• path (required): Vault-relative path (e.g., "Studies/MATH 31AH/Vectors.md")

Returns:

• content: Full markdown content

• frontmatter: Parsed YAML (or null if missing/malformed)

• frontmatterError: Parse error message if YAML is malformed

• outgoingLinks: Array of wikilinks with target, alias, heading, line, column

• headings: Array of headings with level, text, line, id

• stats: Line count, character count, modified timestamp

3. read_notes_batch

Read multiple notes in one call.

Arguments:

• paths (required): Array of vault-relative paths

Returns: Array of ReadNoteResult (same as read_note)

4. search_notes

Full-text search across vault.

Arguments:

• pattern (required): Search string or regex

• isRegex (optional): Treat pattern as regex (default: false)

• folder (optional): Limit search to folder

• limit (optional): Max occurrences per note (default: 10)

Returns: Array of SearchResult with path, match count, and occurrences (with line, column, context).

5. get_vault_structure

Get folder hierarchy with note counts.

Arguments: None

Returns: FolderNode tree with path, name, note count, and children.

Architecture

Error Handling

The server returns structured errors with actionable suggestions:

Error Codes:

• PATH_OUTSIDE_VAULT: Path contains .. or escapes vault

• FILE_NOT_FOUND: File does not exist

• FILE_LOCKED: File in use by another process

• INVALID_FRONTMATTER: YAML parse error

• INVALID_PATH: Path contains illegal characters

Development

Building

Testing

Linting

Roadmap

Phase 1: Foundation & Navigation (Completed)

• MCP server initialization

• Vault access with path security

• Frontmatter and wikilink parsing

• 5 navigation tools (list, read, search, structure)

Phase 2: Note Management (Planned)

• create_note - Create with content + frontmatter

• update_note - Replace or patch sections

• move_note - Relocate + update backlinks

• delete_note - Remove + clean dangling references

Phase 3: Frontmatter Operations (Planned)

• get_frontmatter - Parse metadata

• update_frontmatter - Modify fields

• bulk_update_frontmatter - Update across multiple notes

• audit_frontmatter - Validate against schema

Phase 4: Link Operations (Planned)

• get_links - Outgoing wikilinks

• get_backlinks - Incoming links

• get_all_links - Complete link graph

• insert_link - Add wikilink

• get_orphan_notes - Notes with no links

• get_headings - Heading structure

• find_text_occurrences - Pattern matching

Phase 5: Statistics & Polish (Planned)

• get_tag_list - All tags with counts

• get_note_titles - All titles + aliases

• Comprehensive documentation

• Integration tests

• Performance optimization

Design Principles

1. Stateless: No caching, each call is independent

2. Security: Path validation prevents escapes

3. Rich Metadata: Include line numbers and positions for precise edits

4. Graceful Degradation: Malformed frontmatter returns with error flag

5. SOLID Principles: Clean separation of vault, parser, and tool layers

License

MIT

Contributing

Contributions welcome! This project follows SOLID principles and maintains a strict separation between the I/O layer (server) and intelligence layer (LLM).