Piotr1215/mcp-obsidian

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.

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
• MCP Resources for HATEOAS-style discovery and navigation

Recent Updates

🎉 New Features

• 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

The test suite includes unit tests for all tools and integration tests for the MCP protocol.

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.

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": {
        "lines": [
          { "number": 40, "text": "## Configuration Management", "isMatch": false },
          { "number": 41, "text": "", "isMatch": false },
          { "number": 42, "text": "Managing my dotfiles with stow", "isMatch": true },
          { "number": 43, "text": "has simplified my setup process.", "isMatch": false },
          { "number": 44, "text": "", "isMatch": false }
        ],
        "highlighted": "Managing my **dotfiles** with stow"
      }
    }]
  }],
  "totalMatches": 43,
  "fileCount": 15
}

search-by-title

Search for notes by their H1 title (# Title).

• Fast title-based search
• Case-sensitive/insensitive matching
• Returns title, file path, and line number
• Resource links: Results include MCP resource links for direct note access
• Optional path filtering
• Only matches H1 headings (single #)

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.

• 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.

• Safe deletion with proper validation
• Path security checks

search-by-tags

Find notes containing specific tags.

• Supports both YAML frontmatter and inline #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

MCP Resources

This server implements MCP resource support for HATEOAS-style discovery:

• Automatic Resource Links: All search and list tools return resource links
• Direct Note Access: Use resource URIs to read notes without searching
• Resource URI Format: obsidian-note://relative/path/to/note.md
• Rich Metadata: Resource links include tags, titles, and match counts

Example: When you search for "MCP", results include resource links:

{
  "content": [
    {
      "type": "text",
      "text": "Found 5 matches in 2 files for \"MCP\""
    },
    {
      "type": "resource_link",
      "uri": "obsidian-note://guides/MCP-Guide.md",
      "name": "MCP Implementation Guide",
      "description": "3 matches | Tags: mcp, guide, development"
    }
  ]
}

Agents can then directly read the note using the resource URI, enabling seamless navigation through your knowledge base.

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

See 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