local-image-search-mcp

MCP设计创作

提供方 edujbarrios

设计创作 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaudeCursorZed
查看接入方式

Local Image Search MCP Server is a Model Context Protocol (MCP) service that indexes OCR text, visual content, and metadata from images into a SQLite database, enabling AI assistants to search local image collections using natural language for use cases like finding screenshots, receipts, or photos.

一句话选型结论

按资料字段整理

local-image-search-mcp 属于设计创作类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类设计创作 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

设计创作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

Local Deployment MCP Server Local Image Search Python Natural Language Query OCR Text Extraction Visual Similarity Search Local Privacy Processing SQLite Storage Claude Integration

支持客户端

适用场景

Local DeploymentMCP ServerLocal Image Search

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
/absolute/path/to/local-image-search-mcp/venv/bin/python -m image_mcp_server.server

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
出图与素材

生成配图、图标与素材。

设计稿处理

读取设计稿、批量改尺寸或导出。

内容生成

按主题生成文案与视觉草稿。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在设计创作场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
local-image-search-mcp当前 未标注 stdio · 本地进程 本地部署 有 2026-03-09
Cursor Talk To Figma MCP Da1c7911 40 未标注 未标注 无 2026-05-17
Blender MCP 17 stdio · 本地进程 本地部署 有 2026-05-18
Nova Canvas MCP Server 2 stdio · 本地进程 本地部署 有 2026-05-17
Figma Context MCP 3aaa8d28 未标注 未标注 支持远程部署 无 2026-05-17
kreuzberg 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

设计创作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方edujbarrios上游标注的维护方 edujbarrios
分类设计创作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-03-09上游最后核验时间

详细介绍

11.1 KB
来自项目仓库与上游目录的原文,未做删改

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:```bash
brew install tesseract


**Ubuntu/Debian:**```bash
sudo apt-get install tesseract-ocr

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

2. Clone & Install```bash

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```bash
# 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:```bash
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````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):```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"
}
}
}
}


## 📚 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:```bash
# 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:json "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

  • Issues: GitHub Issues
  • Discussions: GitHub Discussions

Made with ❤️ for Claude and the MCP community

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
local-image-search-mcp 怎么安装?

在客户端按下面的安装命令接入:/absolute/path/to/local-image-search-mcp/venv/bin/python -m image_mcp_server.server。装完在客户端配置里引用同一个包或端点。

local-image-search-mcp 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

local-image-search-mcp 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

local-image-search-mcp 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

local-image-search-mcp 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

local-image-search-mcp 能提供哪些能力?

资料显示能力标签包括 Local Deployment、MCP Server、Local Image Search、Python、Natural Language Query、OCR Text Extraction。具体工具清单以官方文档为准。

local-image-search-mcp 需要什么运行环境?

运行时为 python;属于本地进程,需要在本机装好运行环境。

local-image-search-mcp 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-03-09。