AI导哈

本地图片搜索MCP服务器

本地图片搜索MCP服务器是一款模型上下文协议（MCP）服务，通过将图片的OCR文本、视觉内容和元数据索引到SQLite数据库，使AI助手能够用自然语言搜索本地图片库，适用于查找截图、票据、照片等本地图片场景。

  • by edujbarrios
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 edujbarrios/local-image-search-mcp

使用说明

Local Image Search MCP

Have you ever struggled to find a specific image buried somewhere in your local directories? This MCP server is your solution.

Local Image Search MCP is a Model Context Protocol (MCP) server that enables Claude and other AI assistants to search through your local image collections using natural language. Ask questions like "find screenshots with Python tracebacks" or "show me photos with dogs on the beach", and get instant results based on the actual content of your images—not just filenames.

🎯 What This Does

Local Image Search MCP scans your local directories, analyzes each image using OCR, computer vision, and semantic embeddings, then stores everything in a local SQLite database. Claude can then search through your images using natural language queries that understand:

  • Visual content: "find images with red cars" or "photos of mountains"
  • Text inside images: "screenshots containing 'error 500'" or "receipts from March"
  • Semantic concepts: "diagrams or whiteboard photos" or "invoices and bills"
  • Combined queries: "Python code screenshots from last week"

[!WARNING] Privacy Notice: When using API mode, your images and their content will be sent to external cloud services (e.g., OpenAI) for processing. This means private, sensitive, or personal images will be exposed to third-party APIs. Use API mode at your own risk and only with images you're comfortable sharing externally. For maximum privacy, we strongly recommend using local mode (the default), which processes all images entirely on your machine without sending any data to external services. Local models are fully enabled and supported in this repository.

✨ Key Features

  • 🔒 Privacy-first & Local: All data stays on your machine
  • 🧠 Smart Search: Hybrid search combining semantic similarity, OCR text matching, and metadata filters
  • 🏃 Incremental Indexing: Only reprocesses changed files
  • 🎨 Multi-format Support: JPEG, PNG, WebP, HEIC, GIF, BMP, TIFF
  • 📊 Rich Metadata: Extracts EXIF, dimensions, timestamps, and generates captions
  • 🔍 Visual Similarity: Find images visually similar to a reference image
  • ⚡ Production-Ready: Robust error handling, logging, and batch processing

🏗️ Architecture

The project follows a clean separation inspired by whatsapp-mcp:

Design Philosophy:

  • Indexer: Scans directories, analyzes images, extracts metadata, generates embeddings
  • MCP Server: Exposes search and management tools to Claude Desktop/Cursor
  • Storage: SQLite for all metadata, OCR text, captions, tags, and embeddings
  • Modularity: Swap OCR/captioning/embedding providers via adapter pattern

🔧 Installation

Prerequisites

  • Python 3.10 or higher
  • Tesseract OCR (for text extraction)
  • 2-4 GB free disk space for ML models (first run only)

1. Install Tesseract OCR

macOS:

brew install tesseract

Ubuntu/Debian:

sudo apt-get install tesseract-ocr

Windows: Download and install from GitHub releases, then add to PATH.

2. Clone & Install

# Clone the repository
git clone https://github.com/edujbarrios/local-image-search-mcp.git
cd local-image-search-mcp

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Configure Environment

# Copy example config
cp .env.example .env

# Edit .env with your preferences (optional)
# Default settings work for most users

4. Initialize Database

The database is automatically initialized the first time the server runs. You can also do it manually:

python -c "from database_schema import initialize_database_sync; initialize_database_sync('./image_search.db')"

🚀 Usage with Claude Desktop

Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "image-search": {
      "command": "/absolute/path/to/local-image-search-mcp/venv/bin/python",
      "args": [
        "-m",
        "image_mcp_server.server"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/local-image-search-mcp",
        "DATABASE_PATH": "/absolute/path/to/local-image-search-mcp/image_search.db",
        "IMAGE_ANALYSIS_MODE": "local",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Important: Replace /absolute/path/to/local-image-search-mcp with your actual installation path.

Restart Claude Desktop

After updating the configuration, restart Claude Desktop for changes to take effect.

🚀 Usage with Cursor

Configure Cursor

Add to your Cursor MCP settings (Settings → MCP):

{
  "mcpServers": {
    "image-search": {
      "command": "/absolute/path/to/local-image-search-mcp/venv/bin/python",
      "args": ["-m", "image_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/local-image-search-mcp",
        "DATABASE_PATH": "/absolute/path/to/local-image-search-mcp/image_search.db"
      }
    }
  }
}

📚 Available Tools

Once configured, Claude can use these tools:

scan_directory

Index a directory of images for searching.

Claude: scan the directory /Users/john/Pictures/Screenshots

search_images

Search for images using natural language.

Claude: find images with Python error messages
Claude: show me receipts from the last month
Claude: find photos with people wearing red

get_image_details

Get detailed information about a specific image.

Claude: show me details for /Users/john/Pictures/photo.jpg

find_similar_images

Find visually similar images.

Claude: find images similar to /Users/john/Pictures/sunset.jpg

reindex_changed_files

Reindex files that have changed.

Claude: reindex changed files in /Users/john/Documents

list_indexed_directories

List all indexed directories.

Claude: show me all indexed directories

remove_indexed_directory

Remove a directory from the index.

Claude: stop indexing /Users/john/Old Pictures

get_statistics

Get statistics about the image index.

Claude: show me image index statistics

💡 Example Queries

Once your images are indexed, you can ask Claude:

  • "Find screenshots with Python tracebacks"
  • "Show me invoices or receipts from March"
  • "Find images with dogs on the beach"
  • "Look for photos with a red car"
  • "Find diagrams or whiteboard photos"
  • "Search for images containing the text 'reservation confirmed'"
  • "Show me images similar to this screenshot"
  • "Find photos taken with an iPhone"
  • "Look for images wider than 1920 pixels"

⚙️ Configuration

Environment Variables

Variable Default Description
DATABASE_PATH ./image_search.db SQLite database location
IMAGE_ANALYSIS_MODE local Analysis mode: local, api, or hybrid
MAX_WORKERS 4 Number of parallel indexing workers
BATCH_SIZE 10 Images processed per batch
LOG_LEVEL INFO Logging level

Analysis Modes

  • local (default): Uses local ML models (BLIP, CLIP, Tesseract)

    • Pros: Free, private, no API limits
    • Cons: Slower, requires model downloads (~2GB first run)

  • api: Uses cloud APIs (OpenAI Vision, etc.)

    • Pros: Faster, better quality
    • Cons: Costs money, requires API keys, sends images externally
    • Note: API mode not yet fully implemented

  • hybrid: Mix of local and API

    • Future: Use local for basic tasks, API for complex ones

🗄️ Storage

All data is stored in a single SQLite database file:

  • Images table: File paths, hashes, dimensions, timestamps
  • OCR text: Extracted text with confidence scores
  • Captions: Generated descriptions of image content
  • Tags: Automatically extracted keywords
  • Embeddings: 512-dimension CLIP vectors for semantic search
  • EXIF data: Camera settings, GPS, etc.
  • Full-text search indices: For fast text queries

Database Location

By default: ./image_search.db

You can move it anywhere and update DATABASE_PATH in your configuration.

🔒 Security Considerations

What Claude Can Access:

✅ Read any indexed image metadata, captions, OCR text
✅ Search your indexed images by content
✅ Scan any local directory you ask it to
✅ View full file paths of indexed images

❌ Cannot access files outside indexed directories
❌ Cannot modify or delete images
❌ Cannot execute arbitrary code

Privacy:

  • All processing happens locally (in local mode)
  • No images are sent to external services (unless using api mode)
  • Database contains only paths, not image data
  • You control which directories are indexed

Best Practices:

  • Only index directories you're comfortable exposing to Claude
  • Be aware that Claude will see full file paths
  • Review indexed directories periodically
  • Use remove_indexed_directory for sensitive folders

🐛 Troubleshooting

"No images found"

  1. Make sure you've indexed a directory first:

    Claude: scan the directory /path/to/images

  2. Check if images are actually indexed:

    Claude: show me statistics

"Tesseract not found"

Install Tesseract OCR (see Installation section) and ensure it's in your PATH:

# Test if Tesseract is available
tesseract --version

Slow indexing

  • Reduce MAX_WORKERS in .env if system is overloaded
  • OCR and captioning are CPU-intensive; first-time indexing takes time
  • Models are downloaded on first run (~2GB); subsequent runs are faster

Server not appearing in Claude

  1. Check the configuration file path
  2. Verify Python virtual environment path is absolute
  3. Restart Claude Desktop completely
  4. Check Claude logs:
    • macOS: ~/Library/Logs/Claude/mcp*.log
    • Windows: %APPDATA%\Claude\Logs\mcp*.log

"Import error" or "Module not found"

Ensure PYTHONPATH is set correctly in MCP configuration:

"env": {
  "PYTHONPATH": "/absolute/path/to/image-mcp"
}

🛣️ Roadmap

  • [ ] Web UI for browsing indexed images
  • [ ] Support for PDF page rasterization
  • [ ] Video frame extraction and indexing
  • [ ] Face detection and recognition
  • [ ] API mode with OpenAI Vision
  • [ ] Near-duplicate detection using perceptual hashes
  • [ ] Advanced filters (date ranges, camera settings, etc.)
  • [ ] Export/import index functionality
  • [ ] Docker containerization

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Follow existing code style (Black, type hints, docstrings)
  4. Add tests for new functionality
  5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

  • Inspired by whatsapp-mcp architecture
  • Built with MCP Python SDK
  • Uses BLIP for image captioning, CLIP for embeddings, Tesseract for OCR

📞 Support

Made with ❤️ for Claude and the MCP community

相关 MCP