gthumb-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| XDG_CACHE_HOME | No | Thumbnail cache root. | ~/.cache |
| GTHUMB_DATA_DIR | No | Location of gThumb catalogs. | ~/.local/share/gthumb |
| GTHUMB_CONFIG_DIR | No | Location of tags.xml (gThumb config directory). | ~/.config/gthumb |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_catalogsA | List all gThumb catalogs and saved searches with their item counts. |
| get_catalogB | Get the list of image files stored in a gThumb catalog or saved search. |
| create_catalogB | Create a new, empty gThumb catalog. Use a relative path like 'Random/Trips' to place it in a subfolder. |
| delete_catalogB | Delete a gThumb catalog (.catalog) or saved-search (.search) file. |
| add_to_catalogB | Add image files to a gThumb catalog (duplicates are skipped). |
| remove_from_catalogC | Remove image files from a gThumb catalog. |
| list_tagsA | List all tags known to gThumb (from ~/.config/gthumb/tags.xml). |
| create_tagC | Create a new tag in gThumb. |
| delete_tagA | Delete a tag definition (does not rewrite images; use set_tags to untag files). |
| rename_tagB | Rename a tag in gThumb's tag list (and its cached search snapshot). |
| 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 |
| get_image_infoB | Get image details: dimensions, format, camera, date, GPS, and gThumb metadata (title, description, tags, rating). |
| 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. |
| 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. |
| 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. |
| 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. |
| 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). |
| 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. |
| get_imageB | Get an image's full content for viewing, downscaled to fit max_size pixels. |
| open_in_gthumbC | Open a file (or directory) in the gThumb desktop application. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.