# 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](https://github.com/BurntSushi/ripgrep) installed and available in PATH
- An Obsidian vault
### Install ripgrep
**Windows:**
```powershell
# Using winget (recommended)
winget install BurntSushi.ripgrep.MSVC
# Using chocolatey
choco install ripgrep
# Using scoop
scoop install ripgrep
```
**macOS:**
```bash
brew install ripgrep
```
**Linux (Ubuntu/Debian):**
```bash
sudo apt install ripgrep
```
### Install the MCP Server
```bash
# 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`
```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):**
```bash
export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
```
**Configuration File:**
Create `~/.rgrep-mcp.json`:
```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:**
```bash
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.
