{"id":"5fd55a1d-818d-445c-90d8-f753fdf7aa6e","slug":"mitsuke","kind":"mcp","name":"mitsuke","summary":"Local AI image and video search for artists and filmmakers: find images and video shots in your own folders by words, by example, or both. EmbeddingGemma 2 on Apple Silicon (MLX), with a web app, CLI","owner":"kanaworksai-hue","repoUrl":"https://github.com/kanaworksai-hue/mitsuke","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-21T07:58:29.000Z","addedAt":"2026-10-28T09:13:39.964Z","logoUrl":"https://avatars.githubusercontent.com/u/238872252?u=54b90dd431575d796dabf460f21b77a7010cd783&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media","search","cloud-infra"],"tags":["apple-silicon","claude-code","embeddinggemma","image-search","local-ai","mlx","semantic-search","video-search"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T09:23:40.109Z","sample":false,"url":"https://conduits.dev/tools/mitsuke","language":"Python","transports":["stdio"],"install":{"pypi":"mitsuke"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"
\n\n\"Mitsuke\n\n

\n \"License:\n \"macOS\n \"MCP\n \"Python\n \"Tests\"\n \"GitHub\n

\n\n

\"\" A KanaWorks_AI project

\n\n**English** | [简体中文](README.zh-CN.md) | [日本語](README.ja.md)\n\n[Quick start](#-quick-start) · [Use it from your agent](#-use-it-from-your-agent) · [Web app](#%EF%B8%8F-the-web-app) · [Commands](#-commands) · [FAQ](#-faq) · [⭐ Star](#-like-it-star-it)\n\n
\n\n**Mitsuke 見つけ** (Japanese for \"find\") is a local AI image and video search tool for artists, illustrators and filmmakers. Describe a picture in English, Japanese, Chinese or many other languages (\"foggy bridge at dawn\", \"雪の中の鳥居\", \"云雾缭绕的水墨山水\"), or show it another picture (\"like this, but at night\"). Mitsuke finds it in your own folders: photos, camera RAW, PSD, EXR / HDR, and the right shot inside your videos. It runs entirely on your Mac using Google's [EmbeddingGemma 2](https://huggingface.co/google/embeddinggemma-2), so your images never leave your computer.\n\nUse it in a local web app, from the command line, or let your AI agent (Claude Code, Codex, Cursor, …) search for you through MCP.\n\n

\n \"The\n
The web app searching a reference library of public-domain images. Ukiyo-e bridges show up next to the photos: the search goes by what is in the picture, not by file name.\n

\n\n## ✨ Highlights\n\n\n\n\n\n\n\n\n
🔎
Search by meaning
Words, an example image, or both, with a slider to balance them		🎞️
Made for real libraries
RAW, PSD / PSB, EXR / HDR, HEIC, and videos searched shot by shot		🤖
Agent-ready
MCP server, JSON CLI and a skill, so your agent can find images and video shots and show them to you		🔒
Local
Runs on Apple Silicon with MLX. No account, no upload, no API key
\n\n- **Keeps up with your folders:** while the web app or `mitsuke index --watch` is running, new and changed files are indexed automatically. Moved and renamed files are recognized and keep their index entries.\n- **Moodboards:** collect results on moodboards, then use a whole moodboard as your query.\n- **Never touches your files:** Mitsuke only reads them. The index and thumbnails are stored in separate folders.\n\n## 🧭 How it works\n\n```mermaid\nflowchart LR\n F[\"Your folders
photos · RAW · PSD · EXR · video\"] --> I[\"mitsuke index
decode · cut video into shots\"]\n I --> M[\"EmbeddingGemma 2
MLX on Apple Silicon\"]\n M --> D[\"Local index
SQLite + vectors\"]\n Q[\"“foggy bridge at dawn”
or an example image\"] --> M\n M --> S[\"Search
compare with every image and shot\"]\n D --> S\n S --> R[\"Web app · CLI · MCP
for you and your agent\"]\n```\n\nImages and words are mapped into the same embedding space, so a sentence, a picture, or a mix of both can be compared with every image and video shot in your library.\n\n## 🚀 Quick start\n\n**Requirements:**\n\n- Apple Silicon Mac (M1 or later)\n- [`uv`](https://docs.astral.sh/uv/) (`brew install uv`). It installs Python for you.\n- About 4 GB of free disk space: the model is about 1.5 GB, and the packages and the index take the rest\n\n> [!TIP]\n> **Let your agent install it.** Paste this into Claude Code, Codex or another coding agent:\n> *\"Install Mitsuke from https://github.com/kanaworksai-hue/mitsuke by following its INSTALL.md.\"*\n>\n> The agent follows [`INSTALL.md`](INSTALL.md): it checks your Mac, installs the `mitsuke` command, downloads the model, asks which folders to index, chooses between the CLI and the MCP server, installs the skill and tells you how to open the web app.\n\nTo install it yourself:\n\n```bash\nuv tool install \"mitsuke @ git+https://github.com/kanaworksai-hue/mitsuke\"\nmitsuke doctor --download # checks the setup and downloads the model (once)\nmitsuke serve --open # the web app at http://127.0.0.1:8737; add folders there\n```\n\nOr skip the web app and do it all from the command line:\n\n```bash\nmitsuke add ~/Pictures/References ~/Work/Concept\nmitsuke index # safe to stop with Ctrl-C; run it again to resume\nmitsuke search \"雪の中の鳥居\"\nmitsuke similar ~/Desktop/this_composition.jpg\n```\n\n## 🤖 Use it from your agent\n\nOnce it is installed, just ask: *\"find the foggy harbor photos in my Japan trip folder\"*, *\"collect references for a candle-lit interior and put the best ones on a moodboard\"*, *\"find the shot in my videos where the dragon appears\"*. The agent uses one of these:\n\n- **MCP server:** `mitsuke mcp` (stdio). The model stays loaded after the first call, so later searches are fast.\n\n ```bash\n claude mcp add --scope user mitsuke -- \"$(command -v mitsuke)\" mcp # Claude Code\n codex mcp add mitsuke -- \"$(command -v mitsuke)\" mcp # Codex\n ```\n\n Tools: `search` (words, example images, a moodboard, or a mix), `similar`, `view_images` (a contact sheet the agent can look at), `file_info`, `open_file`, seven moodboard tools, `status`, `add_folder`, `remove_folder`, `index`, `web_link`.\n- **CLI:** every command takes `--json`, for example `mitsuke search \"at night\" --like 12 --json`.\n- **Skill:** `mitsuke skill install` puts a skill in `~/.claude/skills/mitsuke`. It tells the agent when to use Mitsuke and how to show you results, with a link that opens the same search in the web app.\n\n
\nClaude Desktop, Cursor and other MCP clients\n\nUse the absolute path of the command (desktop apps don't search your shell's `PATH`):\n\n```json\n{ \"mcpServers\": { \"mitsuke\": { \"command\": \"/Users//.local/bin/mitsuke\", \"args\": [\"mcp\"] } } }\n```\n\nIf you set `HF_HOME` or `MITSUKE_HOME` in your shell, pass them in an `\"env\"` block too, so the server finds the downloaded model and your index.\n
\n\n## 🖼️ The web app\n\n`mitsuke serve --open` starts it. It only listens on `127.0.0.1` and keeps the index up to date while it runs. The interface is in English, Japanese and Chinese, with dark and light themes.\n\n- **One search box for everything:** type in any language (your usual dictation tool works too), or drop, paste or pick an image. Images and words combine (\"this composition\" + \"at night\"), with a slider to balance the two.\n- **Video:** each video is split into shots. A search lands on the matching shot and plays it from there.\n- **Moodboards:** drag results onto a moodboard (or press B), then use the whole moodboard as your query.\n- **Built for daily work:** a square grid or rows that keep each image's shape, a size slider, full-screen preview (Space), arrow keys, S for similar images, R to reveal in Finder, and filters by folder and file type. In Chrome or Edge, drag a result to Finder to get a copy of the original file.\n\n## 📋 Commands\n\n| Command | What it does |\n|---|---|\n| `mitsuke add …` / `remove …` / `roots` | Manage library folders (removing never touches your files) |\n| `mitsuke index [--watch] [--quality fast\\|default\\|best]` | Index new and changed files. `--watch` keeps running and follows changes |\n| `mitsuke search \"\" [-k 20] [--root F] [--kind raw,psd,exr,video]` | Find images and video shots by description |\n| `mitsuke search [\"\"] [--like …] [--board ID] [--text-weight 0.5]` | Image + words (\"like this, but at night\"), or a whole moodboard as the query |\n| `mitsuke similar ` | Find images that look like an image (inside or outside the library) |\n| `mitsuke board list\\|create\\|show\\|add\\|remove\\|rename\\|delete` | Moodboards (shared with the web app) |\n| `mitsuke show [--open\\|--reveal]` | Details of one file; open it or show it in Finder |\n| `mitsuke web [\"\"] [--board ID] [--start] [--open]` | A link that opens a search or a moodboard in the web app (`--start` launches the app in the background) |\n| `mitsuke serve [--port 8737] [--open] [--no-index]` | The web app (local only); indexes and watches folders in the background |\n| `mitsuke mcp` | MCP server on stdin/stdout for AI agents |\n| `mitsuke skill install [--dir D]` | Install the agent skill (default `~/.claude/skills`) |\n| `mitsuke status` | What is indexed, pending and failed |\n| `mitsuke doctor [--download]` | Check Python, decoders, model, disk and folders |\n\nEvery command accepts `--json` for agents and scripts (`index` prints one JSON event per line).\n\n
\nSupported formats\n\nJPEG, PNG, WebP, HEIC / HEIF, AVIF, TIFF (including 16-bit), GIF, BMP, TGA, JPEG 2000, PSD / PSB, camera RAW (CR2, CR3, NEF, ARW, RAF, ORF, RW2, DNG and more), OpenEXR and Radiance HDR (tone-mapped for search), and video (MP4, MOV, M4V, MKV, WebM, AVI, searched shot by shot).\n
\n\n
\nWhere the data lives\n\n- Index: `~/Library/Application Support/Mitsuke`\n- Thumbnails: `~/Library/Caches/Mitsuke`\n- Model: the Hugging Face cache (`~/.cache/huggingface`, or `$HF_HOME` if set)\n\nSet `MITSUKE_HOME=` to keep the index and thumbnails somewhere else.\n
\n\n## ❓ FAQ\n\n
\nDoes anything get uploaded?\n\nNo. Your images, searches and index stay on your Mac. Installing downloads the Python packages, and the model is downloaded once from Hugging Face. After that, the Hugging Face library checks for model updates when it loads the model; set `HF_HUB_OFFLINE=1` to turn that off. The web app only listens on `127.0.0.1`.\n
\n\n
\nDoes it run on Windows, Linux or Intel Macs?\n\nNot yet. It needs an Apple Silicon Mac, because the model runs on [MLX](https://github.com/ml-explore/mlx).\n
\n\n
\nWhich languages can I search in?\n\nEmbeddingGemma 2 is multilingual. English, Japanese and Chinese all work well, and you can mix them. To search by voice, use your Mac's dictation or any voice input tool.\n
\n\n
\nCan it search the audio or the dialogue in my videos?\n\nNo. Videos are searched by what is on screen, shot by shot.\n
\n\n
\nCLI or MCP, which should my agent use?\n\nMCP, if your agent's app supports it and you search often: the model stays loaded (a few GB of memory while the session is open). The CLI loads the model on each call (a few seconds) but leaves nothing running. [`INSTALL.md`](INSTALL.md) has the full checklist the agent uses to decide.\n
\n\n## 🗺️ Roadmap\n\n- [x] Text, image and image + text search; video shots; EXR / HDR\n- [x] Web app, CLI, MCP server and agent skill\n- [ ] Filter by color\n- [ ] Index ComfyUI / Automatic1111 prompts stored in PNG files\n- [ ] Export moodboards\n\nIssues and pull requests are welcome.\n\n## ⭐ Like it? Star it\n\nIf Mitsuke found an image or shot you needed, please click **⭐ Star** at the top of the [repository page](https://github.com/kanaworksai-hue/mitsuke). It's free, takes a second, and helps more than you might think:\n\n- **More people find it.** Stars make the project easier to discover on GitHub, so more artists and filmmakers get to use it.\n- **It keeps the project going.** Every star shows that people find Mitsuke useful, and that's what keeps new features coming.\n\nOther ways to help: [open an issue](https://github.com/kanaworksai-hue/mitsuke/issues) for a bug or an idea, or share how you use it on X and tag [@KanaWorks_AI](https://x.com/KanaWorks_AI).\n\n## 🛠️ Development\n\n```bash\nuv sync\nuv run pytest # offline tests with a fake embedder; no model or GPU needed\nuv run pytest -m model # checks with the real model\nuv run mitsuke serve # run from the checkout\n```\n\n```\nsrc/mitsuke/\n cli.py commands (argparse, --json everywhere)\n indexer.py scan → embed, resumable; moves and renames keep their vectors\n search.py cosine search, image + text fusion, filters\n server.py the local web app (standard library HTTP server)\n mcp.py the MCP server (stdio JSON-RPC)\n video.py shot detection and shot thumbnails\n decode.py RAW / PSD / EXR / HDR / HEIC previews\n web/ the web app (plain JS, no build step)\n skill/ the agent skill\n```\n\n## 📄 License and credits\n\n- **This project:** [MIT](LICENSE).\n- **Model:** [EmbeddingGemma 2](https://huggingface.co/google/embeddinggemma-2) by Google, licensed under Apache 2.0. It is downloaded from Hugging Face ([MLX conversion](https://huggingface.co/mlx-community/embeddinggemma-2-bf16)), not distributed here.\n- **Built on:** [MLX](https://github.com/ml-explore/mlx), [mlx-vlm](https://github.com/Blaizzy/mlx-vlm), [OpenCV](https://opencv.org), [Pillow](https://python-pillow.org), [rawpy](https://github.com/letmaik/rawpy), [psd-tools](https://github.com/psd-tools/psd-tools) and the [Model Context Protocol](https://modelcontextprotocol.io).\n- **Screenshots:** the images in the demo library are public-domain and CC0 works from Wikimedia Commons ([list](docs/assets/demo-credits.md)).\n- **Brand:** the KanaWorks_AI name, logo and the Kana character are © KanaWorks_AI and are **not** covered by the MIT license. See [docs/brand](docs/brand/README.md).\n\nThis is an independent project. It is not affiliated with or endorsed by Google, Apple or Anthropic.\n\n
\n\n
\n\n\"Kana,\n\n

Made with ♥ by KanaWorks_AI

\n\n

If Mitsuke saves you time, a ⭐ helps the project keep going and helps others find it. More projects: github.com/kanaworksai-hue

\n\n
\n"}