🔍 Better Finder MCP

Git-like workflow for intelligent file search and Claude MCP integration

Better Finder transforms file discovery with semantic search, hybrid matching, and a familiar Git-style workflow. Index your documents, search with natural language, and integrate seamlessly with Claude Desktop.

🚀 Quick Start

Installation

# Clone and install
git clone https://github.com/GitHamza0206/better-finder-mcp.git
cd better-finder-mcp
uv venv
source .venv/bin/activate
pip install -e .

# Install it globally with uv
uv tool install -e .

Basic Workflow

# 1. Stage files for indexing (like git add)
better-finder add ~/Documents

# 2. Check what's staged
better-finder status

# 3. Index staged files
better-finder index

# 4. Search your files
better-finder search "quarterly financial reports"

📋 Commands

File Staging

• better-finder add - Stage files or Documents for indexing
• better-finder rm - Remove files from staging
• better-finder status - Show staged files
• better-finder index - Index staged files

Search & Management

• better-finder search - Search indexed files
• better-finder stats - Show index statistics
• better-finder clear-index - Clear all indexed data
• better-finder server - Start MCP server for Claude

Utilities

• better-finder show - Display file content
• better-finder remove-file - Remove file from index

🎯 Key Features

Hybrid Search

Combines semantic search, keyword matching, and fuzzy filename search for comprehensive results.

Git-like Workflow

Familiar staging process gives you precise control over what gets indexed.

.betterfinderignore Support

Use ignore patterns to exclude sensitive files:

# .betterfinderignore
secrets/
*.key
temp-*.pdf
node_modules/

Supported File Types

• Documents: PDF, DOC, DOCX, TXT, MD, RTF, ODT
• Spreadsheets: XLSX, XLS, CSV, ODS
• Presentations: PPTX, PPT
• Data: JSON, XML

Claude MCP Integration

Start the MCP server to use Better Finder directly within Claude Desktop:

better-finder server

Add to your Claude Desktop config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "better-finder": {
      "command": "better-finder",
      "args": ["server"]
    }
  }
}

🔧 Configuration

Better Finder uses smart defaults:

• Default scan paths: ~/Documents, ~/Desktop, ~/Downloads
• Ignored directories: .git, node_modules, .venv, cache folders
• Chunk size: 2000 characters for better context
• Search threshold: 0.4 for comprehensive results

💡 Examples

Document Discovery

# Find presentations about sales
better-finder search "sales presentation Q4"

# Look for specific file types
better-finder search "budget" --type excel

# Get more results
better-finder search "meeting notes" --max 20

Staging Workflow