gthumb-mcp
Uses the freedesktop.org thumbnail cache and thumbnailer specification to read and generate shared thumbnails, so gThumb and other compliant applications reuse cached thumbnail images.
Integrates with gThumb, GNOME's image library application, exposing catalogs, tags, star ratings, comments, thumbnails, and search to AI agents by reading and writing gThumb's native catalog/tag files and embedded XMP metadata.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gthumb-mcp find my images tagged Beach and rate them 5 stars"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gthumb-mcp
An MCP (Model Context Protocol) server that exposes a gThumb image library to AI agents: catalogs, tags, star ratings, comments, thumbnails and search.
It works directly with gThumb's own data — no database, no duplication:
Data | Location | Access |
Catalogs & saved searches |
| read + write |
Tag definitions |
| read + write |
Per-tag search snapshots |
| read |
Ratings, tags, title, comment | embedded XMP inside the image files | read + write via |
Tags (comment sidecars) |
| read + write |
Thumbnails |
| read + write |
gThumb picks up everything this server writes on its next refresh — and vice versa.
Requirements
Linux with gThumb 3.12 (other 3.x versions likely work)
Python 3.12+ and uv
exiftool —
sudo apt install libimage-exiftool-perl(everything except the metadata tools works without it)
Related MCP server: Apple Photos MCP
Install
uv syncRun
uv run gthumb-mcp # MCP stdio serverRegister with an MCP client
opencode (~/.config/opencode/opencode.json):
{
"mcp": {
"gthumb": {
"type": "local",
"command": [
"uv", "--directory", "/absolute/path/to/gthumb-mcp", "run", "gthumb-mcp"
],
"enabled": true
}
}
}Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"gthumb": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/gthumb-mcp", "run", "gthumb-mcp"]
}
}
}Tools
Catalogs
Tool | Description |
| All catalogs and saved searches with item counts |
| The files stored in a catalog |
| New, empty catalog (supports subfolders, e.g. |
| Delete a catalog or saved-search file |
| Add images (duplicates skipped) |
| Remove images |
Tags
Tool | Description |
| All tags known to gThumb |
| Manage tag definitions |
| Multi-tag search: |
Image metadata (embedded XMP, same fields gThumb writes)
Tool | Description |
| Dimensions, format, camera, date, GPS, title, description, tags, rating |
| Star rating — embedded XMP + comment sidecar |
| Set ( |
| Title/comment/location — written to both the comment sidecar and embedded XMP; only non- |
Search & view
Tool | Description |
| Filter by filename glob, tag, rating and modification date |
| From the shared thumbnail cache ( |
| Image content, downscaled, for model viewing |
| ComfyUI workflow embedded in an image, with a summary (see below) |
Convenience
Tool | Description |
| Open a file or directory in the gThumb desktop app |
ComfyUI workflow delivery
Images saved by ComfyUI embed their generation graph as PNG text chunks
(workflow: the UI graph, and prompt: the API-format graph). The
get_comfyui_workflow tool returns both as parsed JSON plus a best-effort
summary, so an agent can understand — and even recreate — how an image was
generated:
{
"has_workflow": true,
"node_count": 14,
"models": ["SD1.5/Characters/character-lora-v50.safetensors",
"SD1.5/Improve/add_detail.safetensors"],
"positive_prompt": "a photo of a …",
"negative_prompt": "watermark",
"workflow": { "…": "full UI graph, drag-and-droppable back into ComfyUI" },
"prompt": { "…": "API-format graph (with include_prompt=true)" }
}get_image_info includes a has_comfyui_workflow flag for cheap availability
checks. JPEGs saved by ComfyUI (workflow embedded in the EXIF UserComment)
are supported as a fallback. Prompt extraction is best-effort — third-party
node collections wire samplers differently. When the sampler's prompt links
cannot be resolved (e.g. rgthree "Anything Everywhere" / "Prompts Everywhere"
wiring), the summary falls back to the first two text-encoding nodes by node
id and, when present, to the API-format prompt chunk. The complete graph
JSON is always delivered regardless.
Example session
User: Show me my catalogs, then the images tagged Beach.
{"tool": "list_catalogs"} → [{"name": "Favorites", "type": "catalog", "file_count": 42}, …] {"tool": "find_images_by_tag", "arguments": {"tag": "Beach"}} → {"source": "snapshot", "count": 118, "files": ["/home/user/Pictures/2024-07/beach_001.jpg", …]}User: Rate the first one 5 stars.
{"tool": "set_rating", "arguments": {"path": "/home/user/Pictures/2024-07/beach_001.jpg", "rating": 5}} → {"path": "/home/user/Pictures/2024-07/beach_001.jpg", "rating": 5}
How it works
Catalogs are parsed and rewritten as XML in exactly gThumb's format. All writes are atomic (temp file +
os.replace), so a crash can't corrupt gThumb's files.Tags, titles, comments and ratings are read/written as embedded XMP via exiftool and as gThumb comment sidecars (
<folder>/.comments/<image>.xml). Which store the gThumb UI uses depends on the build: exiv2-linked builds read embedded XMP, while Debian's gThumb 3.12 package has no exiv2 linkage and uses sidecars exclusively (regardless of the store-metadata-in-files setting) — so both are kept in sync:gThumb field
XMP field
Sidecar element
Title
XMP-dc:Title<caption>Description / comment
XMP-dc:Description<note>Tags
XMP-dc:Subject(list)<categories><category value=…/>Rating
XMP-xmp:Rating(integer 0–5)<rating value="N"/>Tag searches and
get_image_inforead both stores and merge results. Note the exiftool list semantics used here: plain=assignments replace the whole tag list,+=appends, and an empty list withreplace=trueclears it.Legacy keyword stores are cleared, not just dc:subject. Files tagged by other tools often carry keywords in additional embedded stores — the IPTC IIM
Keywordsblock and the XMPIptc4xmpCore:Keywordsproperty (read-only in exiftool, so a plain tag rewrite can never remove it).set_tagswithreplace=truetherefore wipes every keyword representation with-xmp:all= -iptc:all=first and rebuilds from scratch (re-applying rating, title, description and location afterwards; PNG text chunks such as embedded ComfyUI workflows are unaffected). Append mode unions all existing stores and only creates an IPTC block where one already existed.get_image_infoand tag searches merge all embedded keyword stores, so stale ghosts can neither hide nor leak into results.Thumbnails follow the freedesktop thumbnailer spec: the cache key is the MD5 of the image's
file://URI, and generated thumbnails carry the spec'sThumb::URI/Thumb::MTimeannotations. gThumb shares this cache, so thumbnails are generated at most once, no matter who requests them.find_images_by_tagreads gThumb's cached per-tag snapshot by default (fast, updated whenever gThumb runs a tag search). Pass adirectoryto instead scan the embedded XMP of files live — slower, but reflects the current file contents.If gThumb is running while catalogs change externally, refresh/reopen its library view to see the updates.
Configuration
Environment variable | Default | Purpose |
|
| tags.xml location |
|
| catalogs location |
|
| thumbnail cache root |
These redirects are mainly useful for testing; no gThumb installation is touched by the test suite.
Development
uv sync
uv run pytest # 13 tests; exiftool-dependent tests skip if exiftool is missingProject layout:
src/gthumb_mcp/
├── server.py # FastMCP-style server: 20 tools, stdio transport
├── paths.py # gThumb data locations (env-overridable)
├── catalogs.py # .catalog / .search XML parsing and atomic writing
├── tags.py # tags.xml and per-tag search snapshots
├── metadata.py # exiftool wrapper for embedded XMP
├── sidecars.py # .comments comment sidecars (UI-visible tags)
├── comfyui.py # embedded ComfyUI workflow extraction
├── thumbnails.py # freedesktop thumbnail cache
└── util.py # file:// URI conversion, atomic writesLicense
Available Tools
20 toolsadd_to_catalogB
Add image files to a gThumb catalog (duplicates are skipped).
Inputs: name (required), paths (required). Returns: result
create_catalogB
Create a new, empty gThumb catalog. Use a relative path like 'Random/Trips' to place it in a subfolder.
Inputs: name (required). Returns: result
create_tagC
Create a new tag in gThumb.
Inputs: tag (required). Returns: result
delete_catalogB
Delete a gThumb catalog (.catalog) or saved-search (.search) file.
Inputs: name (required). Returns: result
delete_tagA
Delete a tag definition (does not rewrite images; use set_tags to untag files).
Inputs: tag (required). Returns: result
find_imagesC
Find images under a directory, optionally filtered by filename pattern (glob), tag, minimum rating (0-5) or modification date (ISO, e.g. 2025-01-01).
Inputs: directory (required), tag, limit, min_rating, +3 more. Returns: result
find_images_by_tagsA
Find images by multiple gThumb tags. match='AND': images having ALL tags;
match='OR': images having AT LEAST ONE tag. Reads gThumb's cached tag snapshots
by default; pass directory to instead scan embedded XMP metadata live.
Inputs: tags (required), match, directory. Returns: result
get_catalogB
Get the list of image files stored in a gThumb catalog or saved search.
Inputs: name (required). Returns: result
get_comfyui_workflowA
Get the ComfyUI workflow embedded in an image (PNG text chunks), if any: the full UI graph, plus a summary (node count, models, positive/negative prompts). Set include_prompt=true to also return the API-format 'prompt' graph.
Inputs: path (required), include_prompt. Returns: result
get_imageB
Get an image's full content for viewing, downscaled to fit max_size pixels.
Inputs: path (required), max_size.
get_image_infoB
Get image details: dimensions, format, camera, date, GPS, and gThumb metadata (title, description, tags, rating).
Inputs: path (required). Returns: result
get_thumbnailA
Get an image's thumbnail (128px 'normal' or 512px 'large') from the shared freedesktop thumbnail cache used by gThumb, generating one if missing.
Inputs: path (required), size.
list_catalogsA
List all gThumb catalogs and saved searches with their item counts.
Inputs: no named parameters. Returns: result
list_tagsA
List all tags known to gThumb (from ~/.config/gthumb/tags.xml).
Inputs: no named parameters. Returns: result
open_in_gthumbC
Open a file (or directory) in the gThumb desktop application.
Inputs: path (required). Returns: result
remove_from_catalogC
Remove image files from a gThumb catalog.
Inputs: name (required), paths (required). Returns: result
rename_tagB
Rename a tag in gThumb's tag list (and its cached search snapshot).
Inputs: new (required), old (required). Returns: result
set_commentA
Set an image's title, description (comment) and/or location: written as embedded XMP (exiftool) and to the comment sidecar the gThumb UI reads (sidecar caption/note/place). Only non-None fields are changed.
Inputs: path (required), title, location, description. Returns: result
set_ratingA
Set the gThumb star rating (0-5) of an image: embedded XMP (exiftool) and the comment sidecar the gThumb UI reads. This modifies the file.
Inputs: path (required), rating (required). Returns: result
set_tagsA
Set the gThumb tags of an image. Set replace=false to append instead. Writes both the gThumb comment sidecar (.comments/.xml — what the gThumb UI reads) and embedded metadata (exiftool). Replace mode clears ALL embedded keyword stores (XMP dc:Subject, Iptc4xmpCore:Keywords and IPTC:Keywords) before writing, so no ghost tags survive. This modifies the files.
Inputs: path (required), tags (required), replace. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target a distinct resource+action (catalog CRUD, tag lifecycle, image metadata writes, read-only viewers). The main overlap is find_images versus find_images_by_tags, since find_images already accepts a tag filter, leaving the boundary between them somewhat fuzzy. set_tags/set_comment/set_rating are clearly differentiated by what they modify.
Nearly every tool follows a consistent snake_case verb_noun pattern: create_catalog, delete_tag, set_rating, get_image_info, find_images_by_tags. The lone deviation, open_in_gthumb, is still readable and idiomatic.
At 20 tools the surface leans heavy, but the domain genuinely spans catalogs, tags, image metadata, and viewing. Most tools earn their place, though a few read-only/view helpers could arguably be folded together.
Catalog and tag lifecycles are well covered (create/delete/list/get, add/remove members, tag create/rename/delete/apply/search) plus rating, comment, thumbnail, and full-image reads. Minor gaps remain: no catalog rename, no batch image operations, and no delete-image or listing-by-rating convenience tools.
Related MCP Connectors
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Independent directory of agentic AI tools — search, compare & recommend via MCP. Read-only.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceExposes a visual library with semantic search, tagging, editing, and management of photos as tools for AI agents like Claude Code.13 npm49MIT- AlicenseAqualityBmaintenanceEnables AI agents to search, inspect, organize, and export photos from a local Apple Photos library using natural language, including scene labels, text, faces, places, and albums.1355 npm1MIT
- AlicenseBqualityBmaintenanceEnables AI agents to operate GIMP 3 end-to-end: open and inspect images, call every PDB procedure, apply GEGL filters destructively or as layer effects, measure pixels, render before/after/diff comparisons, cut out subjects with AI segmentation, and run multi-step recipes across folders.3276 PyPI5Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search, list, preview, and export photos from Apple Photos, Google Photos Picker sessions, and local Google Takeout archives using native search and metadata inspection.6 npmMIT