snapsearch-mcp 0.1.0

Your Mac screenshots folder is a disaster. This fixes it — with vision, embeddings, and semantic search.

🧠 snapsearch

Your Mac screenshots folder is a disaster. This fixes it — with vision, embeddings, and semantic search.

An AI agent + custom MCP server that sees your screenshots, understands what's in them, organizes them into clean folders, and lets you find anything with natural language.

Fully local. No cloud uploads. No subscriptions.

---

How it works

screenshot.png
      │
      ▼
GPT-4o vision         "React error about invalid hook call in App.js, line 23"
      │
      ▼
text-embedding-3-small  [0.021, -0.847, 0.334, ...]
      │
      ▼
ChromaDB (local)      stored permanently on disk
      │
      ▼
search("hooks problem") → finds it, even with a garbage filename

---

The result

~/Screenshots/
├── code/
│   ├── errors/         react-hooks-invalid-call.png
│   │                   python-importerror-requests.png
│   └── snippets/       vim-config-lsp-setup.png
├── design/
│   ├── figma/          darkmode-mobile-v3.png
│   └── other/          canva-instagram-post.png
├── chats/              whatsapp-trip-planning-march.png
├── docs/               notion-q2-sprint-board.png
├── memes/              drake-hotline-bling-coding.png
└── web/                vercel-deployment-dashboard.png

---

Architecture

snapsearch (Agent)
    │
    │   MCPServerStdio
    ▼
snapsearch-mcp (MCP server — 8 tools)
    ├── vision.py        GPT-4o vision → structured description
    ├── embeddings.py    OpenAI embeddings + ChromaDB
    └── models.py        Pydantic data models

Why MCP and not just a script?

A script renames blindly. This agent:

• Understands context across a conversation
• Lets you say "actually split design into figma vs other" and re-organizes
• Finds screenshots by meaning: "that slack message about the deploy" works
• Remembers decisions across sessions (ChromaDB persists to ~/.snapsearch/)

---

Setup (No Clone Needed!)

Using uvx (the modern Python alternative to npx), you can run snapsearch instantly without manual cloning or pip installs.

1. Set your Environment Variables

You need to provide your OpenAI API key and optionally your screenshots directory. You can set them in your environment:

export OPENAI_API_KEY=sk-...
export SCREENSHOTS_DIR="/Users/yourname/Desktop" # Optional, defaults to ~/Desktop/screenshots-demo

2. Run the Agent

You can trigger the autonomous organizer right away:

# Full auto-organize (scan → vision → embed → move → rename)
uvx snapsearch

# Semantic search
uvx snapsearch "find my react error screenshots"
uvx snapsearch "show me figma mockups from last month"
uvx snapsearch "that slack conversation about the deployment"

# Partial organize
uvx snapsearch "organize only the code screenshots"

# Index health
uvx snapsearch --stats

---

MCP Tools

Tool	What it does
scan_screenshots	List all images + metadata
read_screenshot	Return base64 image for direct visual inspection
describe_and_index	Main tool — GPT-4o vision + ChromaDB embedding
search_screenshots	Semantic search (meaning, not filenames)
move_screenshot	Move to category subfolder, updates index
rename_screenshot	Human-readable rename, updates index
list_categories	Folder structure + counts
index_stats	ChromaDB health check

---

Use in Claude Desktop (MCP server only)

Because it's distributed on PyPI, using it in Claude Desktop is extremely simple.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "snapsearch": {
      "command": "uvx",
      "args": ["snapsearch-mcp"],
      "env": {
        "SCREENSHOTS_DIR": "/Users/yourname/Desktop",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

---

Where data lives

What	Where
ChromaDB index	~/.snapsearch/chroma/
Your screenshots	wherever SCREENSHOTS_DIR points
Nothing else	nothing is uploaded anywhere

---

Stack

• MCP server — mcp Python SDK v1.27+
• Agent — OpenAI Agents SDK v0.17+
• Vision — gpt-4o (low detail mode — fast + cheap)
• Embeddings — text-embedding-3-small
• Vector DB — ChromaDB (local, persistent)
• Validation — Pydantic v2

---

License

MIT