Obsidian Vault Search for Claude

This MCP server enables Claude to search file content using ripgrep - with extra features for Obsidian. It understands Obsidian-specific elements like wiki links, frontmatter properties, and provides intelligent context about where matches are found.

Available Tools

rg_search_notes

Search for text content within your notes with flexible scope options.

• Search all content, only frontmatter, or only note content
• Get smart context showing which frontmatter property or heading contains each match
• Filter by folder and control result limits

rg_search_links

Find and analyze links throughout your vault.

• Discover wiki links ([[Note Title]]), markdown links, and external URLs
• Filter links by URL patterns or title patterns
• Useful for finding broken links or analyzing your knowledge graph connections

rg_search_backlinks

Find all notes that link to a specific target note.

• Identify which notes reference a particular topic or note
• Understand the context around each backlink reference
• Discover how ideas connect across your vault

rg_search_recent_notes

Find notes modified within specific date ranges.

• Search by modification date using YYYY-MM-DD format
• Useful for reviewing recent work or finding notes from specific time periods
• Combine with other searches to find recent notes about specific topics

rg_search_orphaned_notes

Identify notes that have no incoming or outgoing links.

• Find isolated notes that might need better integration
• Discover forgotten content that could be connected to your knowledge graph
• Useful for vault maintenance and organization

Obsidian-Specific Capabilities

Smart Context Detection

When matches are found, Claude receives intelligent context:

• Frontmatter matches: Shows the property name (e.g., tags, project, status)
• Content matches: Shows the nearest heading (e.g., ## Project Ideas, ### Meeting Notes)
• Nested properties: Handles complex YAML structures in frontmatter

Link Understanding

• Wiki Links: [[Note Title]] and [[Note Title|Display Text]]
• Markdown Links: [Display Text](https://github.com/kpetrovsky/kp-ripgrep-mcp/blob/HEAD/note-file.md) and external URLs
• Frontmatter Links: Links within YAML properties and lists

File Organization

• Folder Filtering: Limit searches to specific directories
• Date-Based Discovery: Find files by modification time
• Vault Structure: Understands Obsidian's file organization patterns

Additional Parameters

Most search tools support these common parameters:

Search Behavior

• case_sensitive: true or false (default: false)
• folder: Limit search to specific folder (e.g., "Daily Notes", "Projects/Active")
• max_results: Number of results to return (1-100, default: 15, automatically capped)
• smart_context: Include context detection (default: true, set to false for faster searches)

Search Scope (for rg_search_notes)

• search_scope:
  • "all" - Search everything (default)
  • "content_only" - Skip frontmatter, search only note content
  • "frontmatter_only" - Search only YAML frontmatter properties

Date Filtering (for rg_search_recent_notes)

• start_date: Start date in YYYY-MM-DD format (e.g., "2024-01-15")
• end_date: End date in YYYY-MM-DD format (e.g., "2024-01-31")

Link Filtering (for rg_search_links)

• link_type: "all", "wiki_links", "markdown_links", or "external_urls"
• url_pattern: Regex pattern to filter URLs
• title_pattern: Regex pattern to filter link titles

Installation

Prerequisites

• Python 3.8 or higher
• ripgrep installed and available in PATH
• An Obsidian vault

Install ripgrep

Windows:

# Using winget (recommended)
winget install BurntSushi.ripgrep.MSVC

# Using chocolatey
choco install ripgrep

# Using scoop
scoop install ripgrep

macOS:

brew install ripgrep

Linux (Ubuntu/Debian):

sudo apt install ripgrep

Install the MCP Server

# Clone the repository
git clone https://github.com/kpetrovsky/kp-ripgrep-mcp.git
cd kp-ripgrep-mcp

# Install the package
pip install -e .

Configure Claude Desktop

Add this configuration to Claude Desktop:

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

{
  "mcpServers": {
    "obsidian-search": {
      "command": "python",
      "args": ["-m", "rgrep_mcp.server"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Replace /path/to/your/obsidian/vault with your actual vault path.

Alternative Configuration

Environment Variable (all platforms):

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"

Configuration File: Create ~/.rgrep-mcp.json:

{
  "vault_path": "/path/to/your/obsidian/vault",
  "default_case_sensitive": false,
  "default_result_limit": 15
}

Example Usage

Ask Claude:

• "Find all notes containing 'machine learning' in my Research folder"
• "Show me notes I modified last week"
• "What notes link to my 'Project Ideas' note?"
• "Find notes with 'productivity' in the tags property"
• "Search for 'meeting' only in note content, not frontmatter"

Troubleshooting

"ripgrep (rg) is not installed or not in PATH"

Verify ripgrep installation:

rg --version

If this command fails, reinstall ripgrep using the instructions above.

"No vault path configured" or "Vault path does not exist"

• Ensure OBSIDIAN_VAULT_PATH environment variable is set correctly
• Verify the path points to your Obsidian vault directory (contains .md files)
• Use absolute paths, not relative paths
• On Windows, use forward slashes or escape backslashes in JSON: "C:/Users/Name/Vault" or "C:\\Users\\Name\\Vault"

Claude isn't finding expected results

• Verify search terms: Check that the content actually exists in your notes
• Check scope: Try "search_scope": "all" first, then narrow down
• Test with simple queries: Start with basic text searches before using complex patterns
• Check folder restrictions: If using the folder parameter, ensure it contains the expected notes

Performance issues with large vaults

• Use folder filtering: Limit searches to specific directories when possible
• Reduce max_results: Start with smaller limits (5-10) for faster responses
• Disable smart_context: Set "smart_context": false for faster searches when context isn't needed
• Be specific: More targeted search terms are faster than broad queries

Date format errors

Use YYYY-MM-DD format for dates:

• ✅ "2024-01-15"
• ✅ "2024-12-31"
• ❌ "01/15/2024"
• ❌ "Jan 15, 2024"

Permission issues

• Ensure Claude Desktop has permission to access your vault directory
• On macOS, you may need to grant Full Disk Access to Claude Desktop in System Preferences

License

MIT License - see LICENSE file for details.