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:trueorfalse(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 URLstitle_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_PATHenvironment 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
folderparameter, 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": falsefor 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.