Content
# 🔍 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
```bash
# 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
```bash
# 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:
```bash
better-finder server
```
Add to your Claude Desktop config (`~/.cursor/mcp.json`):
```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
```bash
# 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
```bash
# 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.**
Connection Info
You Might Also Like
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Fetch
Retrieve and process content from web pages by converting HTML into markdown format.
Context 7
Context7 MCP provides up-to-date code documentation for any prompt.
context7-mcp
Context7 MCP Server provides natural language access to documentation for...
chrome-devtools-mcp
Chrome DevTools for coding agents
memU
MemU is a memory framework for LLM and AI agents, organizing multimodal...