Obsidian MCP Server

MCP server for Obsidian that provides secure, direct file system access to vault files.

Why This Server?

Most existing Obsidian MCP servers rely on the Obsidian REST API plugin, which requires:

• Obsidian to be installed
• Obsidian to be running
• The REST API plugin to be configured

This server instead works directly with Obsidian vault files on disk, making it compatible with setups using obsidian.nvim - a Neovim plugin that provides Obsidian-like features without requiring the Obsidian app.

Logseq and Foam

Any folder of markdown notes works, so the server also reads Foam workspaces and file-based Logseq graphs. Point it at the workspace or graph folder.

For Logseq graphs the server also reads:

• tags:: and other page properties at the top of a page, reported as tags and frontmatter
• title:: as the page title, falling back to the file name, with a___b.md read as a/b
• multi-word #[[tag name]] tags

It skips the copies Logseq keeps under logseq/bak/ and logseq/version-files/, as Logseq does.

Features

• Direct file system access to Obsidian vaults - no Obsidian app required
• Security-first design with path traversal prevention and input validation
• High performance with execution time tracking and resource limits
• Rich search capabilities including regex support and tag-based search
• Metadata support with frontmatter and inline tag parsing

Recent Updates

🎉 New Features

• 🗺️ MOC Discovery: New discover-mocs tool provides a high-level map of your vault's knowledge structure by discovering Maps of Content and their relationships. Start here for 10x faster navigation!
• Resource Links: Search results now include MCP resource links for direct note access
• Context Snippets in Search Results: Search results now include surrounding lines for better context understanding
• Match Highlighting: Search terms are highlighted with bold markers in results
• Improved Search Result Structure: Results are now grouped by file with match counts and snippets

Installation

npm install

Usage

Testing with MCP Inspector

# Replace /home/decoder/dev/obsidian/decoder with your vault path
npx @modelcontextprotocol/inspector node src/index.js /home/decoder/dev/obsidian/decoder

The inspector will open at http://localhost:5173

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run tests with coverage and check thresholds
npm run coverage

# Run mutation testing (all files)
npm run test:mutation

# Run mutation testing (pagination code only - faster)
npm run test:mutation-pagination

Adding to Claude Desktop

To add this server to Claude Desktop, use the Claude CLI:

# Clone this repository
git clone https://github.com/Piotr1215/mcp-obsidian.git
cd mcp-obsidian

# Install dependencies
npm install

# Add to Claude (replace /path/to/your/vault with your Obsidian vault path)
claude mcp add obsidian -s user -- node /path/to/mcp-obsidian/src/index.js /path/to/your/vault

For example, if you cloned the repo to ~/dev/mcp-obsidian and your vault is at ~/Documents/ObsidianVault:

claude mcp add obsidian -s user -- node ~/dev/mcp-obsidian/src/index.js ~/Documents/ObsidianVault

This will add the server to your Claude configuration file (typically ~/.claude.json or ~/.config/Claude/claude_desktop_config.json).

To verify the installation:

claude mcp list

You should see obsidian in the list of available MCP servers.

Vault path

The server expands a leading ~ in the vault path, since MCP clients start it without a shell. It does not expand environment variables such as $HOME.

If the server cannot read the vault, every tool that lists notes returns an error naming the cause instead of an empty result. On macOS, a vault in iCloud Drive, Documents or Desktop needs the app that starts the server, such as Claude or your terminal, to have access under System Settings > Privacy & Security > Files and Folders, or Full Disk Access.

Available Tools

search-vault

Search for content across all notes in your vault.

Features:

• Boolean operators: AND, OR, NOT (also supports &&, ||, -)
• Field specifiers: title:term, content:term, tag:term
• Quoted phrases: "exact phrase"
• Grouping with parentheses: (term1 OR term2) AND term3
• Case-sensitive/insensitive search
• Context snippets: See surrounding lines for each match
• Match highlighting: Search terms are highlighted with bold
• Resource links: Results include MCP resource links for direct note access
• Returns grouped results by file with match counts
• Optional path filtering

Context Options:

• includeContext (default: true) - Show surrounding lines
• contextLines (default: 2) - Number of lines before/after match (0-10)

Examples:

• readme AND install - Find notes containing both words
• title:setup OR tag:documentation - Find by title or tag
• "getting started" -deprecated - Exact phrase, excluding deprecated
• (python OR javascript) AND tutorial - Complex queries with grouping

Example Output with Context:

{
  "files": [{
    "path": "notes/dotfiles.md",
    "matchCount": 3,
    "matches": [{
      "line": 42,
      "content": "Managing my dotfiles with stow",
      "context": {
        "highlighted": "Managing my **dotfiles** with stow"
      }
    }]
  }],
  "totalMatches": 43,
  "fileCount": 15
}

search-by-title

Search for notes by title: the first H1 (# Title), else a title property (YAML title: or Logseq title::), else the file name.

• Fast title-based search
• Case-sensitive/insensitive matching
• Returns title, file path, and line number (null for a file name title)
• Resource links: Results include MCP resource links for direct note access
• Optional path filtering

list-notes

List all markdown files in your vault or a specific directory.

• Returns file paths and total count
• Resource links: Results include MCP resource links for direct note access
• Supports directory filtering

read-note

Read the complete content of a specific note.

• Wikilink-style resolution: Just provide the filename (e.g., bitwarden-cli.md) and the server finds it anywhere in the vault
• Falls back to exact path if provided (e.g., Notes/projects/bitwarden-cli.md)
• Reports ambiguity if multiple notes share the same filename
• Path validation ensures security
• File size limits prevent memory issues

write-note

Create or update a note with new content.

• Atomic writes for data integrity
• Automatic directory creation
• Content size validation

delete-note

Delete a note from your vault. Permanent, there is no trash.

Clients that support MCP elicitation are asked to confirm first, and the prompt shows the note's size, modification date and first line, read off disk rather than taken from the caller's argument. Refusing keeps the note and the tool reports that it did not delete. A decline, a cancel, a timeout and a dead transport all count as a refusal.

Some clients advertise elicitation and then answer it themselves without showing anyone. Codex 0.153.4 returns a decline in about 10ms on its programmatic tool path. The note is kept either way, and the tool says the client answered rather than blaming you for a prompt you never saw.

Clients that do not advertise elicitation delete without a prompt, as before. Set OBSIDIAN_MCP_CONFIRM_DELETE=off to turn the prompt off for clients that do.

append-note

Add content to an existing note without overwriting it, creating the note if it is absent. write-note replaces the whole file; this one does not.

• section appends under a specific heading rather than at the end
• ensureNewline (default true) keeps the appended block from running into the previous line

search-by-tags

Find notes containing specific tags.

• Supports YAML frontmatter, Logseq tags:: properties, inline #tags, and #[[multi word]] tags
• AND operation for multiple tags
• Resource links: Results include MCP resource links for direct note access
• Case-sensitive/insensitive matching

get-note-metadata

Get metadata for one or all notes without reading full content.

• Single note mode: Get metadata for a specific note
• Batch mode: Get metadata for all notes in vault
• Extracts frontmatter, title, tags, and content preview
• Resource links: Results include MCP resource links for direct note access
• Lightweight alternative to reading full notes
• Useful for building note indexes or dashboards

discover-mocs

⭐ RECOMMENDED: Start here! Discover MOCs (Maps of Content) to understand your vault's knowledge structure.

Maps of Content are organizational hub notes (tagged with #moc) that link to related content. They were pioneered by Nick Milo as a flexible alternative to rigid folder structures.

Features:

• Lists all MOCs in your vault with their linked notes
• Shows MOC hierarchy (which MOCs link to other MOCs)
• Displays full list of wikilinks from each MOC
• Provides a high-level map of your vault's organization
• 10x faster navigation - understand structure before searching
• Filter by MOC name or directory

Why use MOCs?

• Context: See what knowledge areas exist in your vault
• Scale: Understand how developed each area is
• Relationships: Discover how topics connect through MOC hierarchy
• Entry points: Find the best starting point for exploration

Example Output:

Found 10 MOCs

📚 Vault Index (24 linked notes)
   Path: 00-INDEX.md
   Links: Work-MOC, AI-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Personal-MOC, Homelab-MOC, MCP-Framework-MOC
   🔗 Links to MOCs: Work-MOC, AI-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Personal-MOC, Homelab-MOC, MCP-Framework-MOC

📚 AI-MOC (61 linked notes)
   Path: _mocs/AI-MOC.md
   Links: chatgpt, ollama, langchain, aider, gp-nvim, MCP-Framework-MOC, ...
   🔗 Links to MOCs: MCP-Framework-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Work-MOC, 00-INDEX

This tool enables agents to understand your knowledge graph structure instantly, making navigation ~10x faster than blind keyword searching.

Security Features

This server implements comprehensive security measures:

• Path Traversal Prevention: All file paths are validated to prevent access outside the vault
• Input Validation: All inputs validated against JSON schemas
• File Size Limits: Configurable limits prevent memory exhaustion (default: 10MB)
• Content Sanitization: Removes potentially harmful null bytes
• Markdown-only Access: Only .md files can be accessed
• Human Confirmation Before Deletion: delete-note asks the user over MCP elicitation, so the go-ahead comes from a person rather than from an argument the model composed. Path validation stops a traversal but not a deletion of the wrong note inside the vault; this is what covers that.

See MCP_SPEC_COMPLIANCE.md for detailed compliance information.

Contributing

1. Ensure all tests pass: npm test
2. Maintain test coverage above 90%: npm run coverage
3. Follow functional programming principles
4. Add tests for new features
5. Update documentation as needed