Ripgrep Search

Efficiently search Obsidian vaults using the ripgrep tool.

View on GitHub →

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](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
}

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

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"

License

MIT License - see LICENSE file for details.

Related Servers