local_media_search_mcp_server by mugdhav - MCP Server

title: Local AI Media Scout - Hackathon Space Submission emoji: 🎬 colorFrom: green colorTo: blue sdk: gradio sdk_version: "6.0.0" app_file: app.py pinned: false tags:

building-mcp-track-consumer
building-mcp-track-creative

🎬 Local AI Media Scout

Privacy-First Semantic Media Search MCP Server

100% Local & Private: Your media stays on your machine. AI runs locally. Zero cloud uploads.

🌟 Overview

Local AI Media Scout is a Model Context Protocol (MCP) server that gives AI assistants (like Claude) access to your local photos and videos through natural language search.

Unlike cloud-based solutions, this tool runs entirely on your local machine using the SigLIP AI model (2x faster than CLIP) to understand the content of your media files.

Perfect for:

🔍 Finding photos/videos using descriptions like "sunset at the beach" or "receipt for coffee"
🤖 Giving Claude Desktop "eyes" to see your local media library
🔒 Users who care about privacy and don't want to upload personal photos to the cloud

✨ Features

Semantic Search: Search by meaning, not just filenames (e.g., "cat sleeping on sofa").
Multi-Modal: Supports both Images (JPG, PNG, WEBP, etc.) and Videos (MP4, MOV, MKV, etc.).
Privacy-First: All processing (indexing & searching) happens on your CPU/GPU.
Dual Interface:
- 🔌 MCP Server: Connects to Claude Desktop.
- 🌐 Web UI: Built-in interface for testing and direct usage.
High Performance: Uses google/siglip-base-patch16-224 and FAISS for fast indexing and retrieval.

🛠️ Installation

Prerequisites

Python 3.10 or higher
Git

1. Clone the Repository

git clone https://github.com/mugdhav/local_media_search_mcp_server.git
cd local_media_search_mcp_server

2. Create a Virtual Environment

It's recommended to use a virtual environment to manage dependencies.

Windows:

python -m venv venv
.\venv\Scripts\activate

macOS/Linux:

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

⚙️ Configuration

Create a .env file in the root directory (optional, defaults will be used):
```
MEDIA_DIR=media
INDEX_DIR=index
```
- MEDIA_DIR: The folder containing your photos and videos (can be an absolute path).
- INDEX_DIR: Where the AI index files will be stored.
Add your media:
- Place your photos and videos in the media folder (or whichever folder you configured).
- Note: The first time you run the server, it will download the AI model (~150MB) and index your files. This may take a few minutes depending on your library size.

🚀 Usage

1. Start the Server

Run the application:

python app.py

You should see output indicating the server has started:

Web UI: http://localhost:7860
MCP Endpoint: http://localhost:7860/gradio_api/mcp/sse

2. Connect to Claude Desktop

To use this with Claude Desktop, you need to add the server configuration to your MCP settings file.

File Location:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "media-search": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

Restart Claude Desktop after saving this file.

3. Using the Web UI

Open http://localhost:7860 in your browser to:

Test search queries.
View index statistics.
Manually trigger a re-index.
Inspect file details.

🤖 Available MCP Tools

When connected to Claude, you can use the following tools:

Tool	Description
`semantic_search`	Search your media using natural language descriptions. Args: `query` (str), `media_type` (all/image/video), `top_k` (int)
`get_media_details`	Get metadata about a specific media file (size, type, path). Args: `file_path` (str)
`get_index_stats`	View statistics about your indexed library (count, size, etc.).
`reindex_media`	Force the server to re-scan your media directory. Args: `force` (bool)

Example Prompts for Claude:

"Find me pictures of my dog playing in the park."
"Do I have any videos of the graduation ceremony?"
"Show me the metadata for the first search result."
"Reindex my media library, I just added some new photos."

🔧 Troubleshooting

First Run Slowness: The first run downloads the SigLIP model. This is normal.
Video Processing: Indexing videos takes longer as it extracts frames to understand the content.
"File not found": Ensure your MEDIA_DIR path is correct in the .env file.
MCP Connection Error: Make sure the server is running (python app.py) before opening Claude Desktop.

📜 License

MIT License

Built for the MCP 1st Birthday Hackathon 🎂