What is Better Finder Mcp

Better Finder MCP is a tool that replaces traditional file finders with an MCP server, enabling intelligent document searches using a Git-like workflow and Claude MCP integration.

Use cases

Use cases include searching for specific financial reports, managing large document collections, retrieving academic papers, and organizing project files in a collaborative environment.

How to use

To use Better Finder MCP, clone the repository, set up a virtual environment, and install the necessary dependencies. You can stage files for indexing, check the status, index the files, and perform searches using natural language queries.

Key features

Key features include hybrid search capabilities that combine semantic search, keyword matching, and fuzzy filename search; a Git-like workflow for precise control over indexing; support for .betterfinderignore to exclude sensitive files; and compatibility with various document types.

Where to use

Better Finder MCP can be used in various fields such as document management, academic research, legal document retrieval, and any environment where efficient file searching is essential.

🔍 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 <path> - Stage files or Documents for indexing
• better-finder rm <path> - Remove files from staging
• better-finder status - Show staged files
• better-finder index - Index staged files

Search & Management

• better-finder search <query> - 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 <file> - Display file content
• better-finder remove-file <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

# Stage entire project documentation
better-finder add ./docs

# Remove sensitive files
better-finder rm ./docs/secrets/

# Check what will be indexed
better-finder status

# Index everything staged
better-finder index

MCP Integration

Once the server is running, ask Claude:

• “Search my documents for budget reports”
• “Find presentations about project timelines”
• “Show me files related to client proposals”

🏗️ Architecture

• File Processors: Extract content from different formats
• FAISS Vector Store: Fast similarity search with sentence transformers
• SQLite Metadata: Efficient file metadata and chunk storage
• Staging System: Git-like file management with JSON persistence
• MCP Server: Model Context Protocol integration for Claude

📊 Performance

• Indexing: ~100-500 files per minute
• Search: Sub-second results
• Memory: ~200-500 MB for typical collections
• Storage: ~1-5 MB per 1000 documents

📝 License

MIT License - see LICENSE file for details.

Made for developers who want intelligent file discovery with familiar Git-like controls.