# Better Finder Mcp

> Replace Finder with an MCP server to search for your documents

- **Type:** MCP server
- **Install:** `agentstack add mcp-githamza0206-better-finder-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [GitHamza0206](https://agentstack.voostack.com/s/githamza0206)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [GitHamza0206](https://github.com/GitHamza0206)
- **Source:** https://github.com/GitHamza0206/better-finder-mcp

## Install

```sh
agentstack add mcp-githamza0206-better-finder-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🔍 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 ` - 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:

```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.**

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [GitHamza0206](https://github.com/GitHamza0206)
- **Source:** [GitHamza0206/better-finder-mcp](https://github.com/GitHamza0206/better-finder-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-githamza0206-better-finder-mcp
- Seller: https://agentstack.voostack.com/s/githamza0206
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.