Skip to main content
Glama
tldev

container-tag-finder

by tldev

Container Tag Finder

A simple API and MCP server that helps AI agents find the latest container image tags.

The Problem

AI agents often struggle with container image versioning:

  • Web searches return outdated or inconsistent information

  • Registry APIs require authentication and specific knowledge

  • The "latest" tag is ambiguous—you usually want the latest semantic version

This project provides a clean API that returns the actual latest version tag, making it easy for agents to pin images to specific versions.

Related MCP server: Docker Hub MCP Server

Quick Start

# Start the API server
docker compose up -d

# Test it
curl http://localhost:8080/latest/nginx

Run the MCP server via Docker

# Interactive mode for MCP
docker compose run --rm mcp

Local Installation

# Clone and install
cd container-tag-finder
pip install -e .

Run the REST API (Local)

# Start the server (with hot reload for development)
RELOAD=true container-tag-finder

# Or directly
python -m container_tag_finder.server

The API will be available at http://localhost:8080. Try:

# Get latest nginx version
curl http://localhost:8080/latest/nginx

# Get latest Redis from Bitnami
curl http://localhost:8080/latest/bitnami/redis

# Get latest KEDA from GitHub Container Registry
curl "http://localhost:8080/latest/ghcr.io/kedacore/keda"

# Get latest PostgreSQL 16.x only
curl "http://localhost:8080/latest/postgres?major=16"

Use as MCP Server

Add to your MCP configuration (e.g., Claude Desktop's claude_desktop_config.json or Cursor's MCP settings):

{
  "mcpServers": {
    "container-tags": {
      "command": "container-tag-mcp",
      "args": []
    }
  }
}

Or with uv:

{
  "mcpServers": {
    "container-tags": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/container-tag-finder", "container-tag-mcp"]
    }
  }
}

Or via Docker:

{
  "mcpServers": {
    "container-tags": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/container-tag-finder/docker-compose.yml", "run", "--rm", "-T", "mcp"]
    }
  }
}

API Reference

GET /latest/{image}

Get the latest semantic version tag for an image. This is the primary endpoint for agents.

Parameters:

  • image (path) - Image reference (e.g., nginx, ghcr.io/owner/repo)

  • include_prerelease (query) - Include RC/beta versions (default: false)

  • major (query) - Only consider this major version (e.g., 16 for PostgreSQL 16.x)

  • pattern (query) - Regex filter for tags

Example Response:

{
  "image": "nginx",
  "registry": "docker.io",
  "repository": "library/nginx",
  "latest_tag": "1.27.3",
  "latest_stable": "1.27.3",
  "full_reference": "nginx:1.27.3",
  "digest": "sha256:abc123...",
  "all_semver_tags": ["1.27.3", "1.27.2", "1.27.1", "1.26.2", ...]
}

GET /tags/{image}

List all tags for an image with semantic version analysis.

Parameters:

  • image (path) - Image reference

  • pattern (query) - Regex filter

  • limit (query) - Max tags to return (default: 50)

GET /compare/{image}?current={tag}

Check if an update is available for a given tag.

Example:

curl "http://localhost:8080/compare/nginx?current=1.25.0"

Response:

{
  "current_tag": "1.25.0",
  "current_is_semver": true,
  "latest_tag": "1.27.3",
  "update_available": true,
  "update_type": "minor",
  "message": "Update available: 1.25.0 → 1.27.3"
}

MCP Tools

The MCP server provides three tools for AI agents:

get_latest_image_tag

Find the latest version of a container image.

Input: { "image": "nginx" }
Output: Latest stable version with full reference

list_image_tags

List available tags for an image.

Input: { "image": "postgres", "pattern": "^16\\." }
Output: All PostgreSQL 16.x tags

check_image_update

Check if an update is available.

Input: { "image": "nginx", "current_tag": "1.25.0" }
Output: Update status and recommendation

Supported Registries

  • Docker Hub (docker.io) - Official and user images

  • GitHub Container Registry (ghcr.io)

  • Quay.io (quay.io)

  • Google Container Registry (gcr.io)

  • Any OCI-compliant registry - Generic support via OCI Distribution API

Image Reference Formats

The API understands these formats:

Input

Registry

Repository

nginx

docker.io

library/nginx

bitnami/redis

docker.io

bitnami/redis

ghcr.io/owner/repo

ghcr.io

owner/repo

quay.io/prometheus/prometheus

quay.io

prometheus/prometheus

gcr.io/project/image

gcr.io

project/image

Version Detection

The API parses semantic versions from tags intelligently:

  • Standard semver: 1.2.3, v1.2.3

  • With prerelease: 1.2.3-rc1, 1.2.3-beta.2

  • With build metadata: 1.2.3+build123

  • Variant suffixes: 1.2.3-alpine, 1.2.3-slim (treated as prerelease)

  • Two-part versions: 1.2 (treated as 1.2.0)

Non-version tags like latest, edge, nightly, sha-abc123 are automatically filtered out.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
ruff format .
ruff check --fix .

Why This Exists

When working with AI coding assistants on containerized applications, I found that:

  1. Asking "what's the latest nginx version?" leads to web searches with outdated results

  2. Agents can't easily query container registries directly

  3. The "latest" tag is what agents default to, but it's bad practice for reproducibility

This API/MCP gives agents a reliable way to find the actual latest semantic version, making it easy to write nginx:1.27.3 instead of nginx:latest.

License

MIT

Available Tools

5 tools
check_image_updateA

Check if a newer version of a container image is available.

Compares a current tag to the latest available version and tells you if an update is available and what type (major, minor, or patch).

Useful for auditing Dockerfiles or Kubernetes manifests to find outdated images.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesImage reference (e.g., 'nginx', 'ghcr.io/owner/repo')
current_tagYesThe current tag being used (e.g., '1.25.0', 'v2.10.0')

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses the main behavior (comparison and update type) but lacks details on error handling, authentication needs, or whether the operation is read-only. The transparency is adequate for a simple check tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no superfluous information. The first sentence directly states the purpose, followed by a brief mechanism and a use case. Minimally sufficient for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity (2 simple params, no output schema), the description covers purpose, use case, and output nature (update type). It omits exact return format, but the mention of 'tells you' and 'major, minor, or patch' provides enough context for agent selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters described. The description adds value by implying semantic versioning (major/minor/patch) and the context of comparing to 'latest available version,' which goes beyond the schema's examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks if a newer version of a container image is available by comparing a current tag to the latest version, and reports the update type (major, minor, patch). This distinct purpose is differentiated from sibling tools like get_latest_image_tag and search_images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage scenario: auditing Dockerfiles or Kubernetes manifests for outdated images. However, it does not explicitly state when not to use this tool or mention alternatives for comparison.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_imageA

Find an image by name, trying multiple registries and namespaces.

BEST PRACTICE: If you only have an application name (like "qui" or "radarr"):

  1. First check the project's GitHub/website to find the correct image path

  2. Look for org/repo pattern (e.g., "autobrr/qui" not just "qui")

  3. Then call this tool with "org/repo" format

This tool will try the name on Docker Hub, GHCR, and Quay.io:

  • "radarr" → tries linuxserver/radarr, bitnami/radarr, etc.

  • "autobrr/qui" → tries Docker Hub first, then ghcr.io/autobrr/qui ✓

LIMITATION: Cannot discover GHCR images without knowing the org name. If searching for a GitHub project's image, use format: "orgname/reponame"

Examples:

  • "nginx" → finds nginx:1.27.3 (official Docker Hub)

  • "autobrr/qui" → finds ghcr.io/autobrr/qui:v0.3.0

  • "linuxserver/radarr" → finds linuxserver/radarr:5.x.x

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesImage name. Use 'org/repo' format for best results (e.g., 'autobrr/qui', 'linuxserver/radarr')

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: tries Docker Hub, GHCR, Quay.io; explains trial order; and clearly states limitation about GHCR org names. No surprises.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with bold sections and bullet points. Slightly long but every sentence adds value. Front-loads purpose and key guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description covers purpose, usage, limitations, and examples comprehensively. No gaps given the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes the 'name' parameter well (100% coverage). The description adds extra value with format advice ('org/repo'), best practices, and concrete examples, exceeding schema info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds an image by name across multiple registries, with specific verb 'Find' and resource 'image'. It distinguishes from siblings by focusing on discovery, not updates or tag listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides best practices (e.g., use org/repo format, check project website) and explicit limitation about GHCR. Lacks explicit when-not-to-use vs sibling tools, but guidance is still strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_latest_image_tagA

Get the latest semantic version tag for a container image.

Use this when you KNOW the exact image path. Returns the latest stable semantic version tag for use in Dockerfiles or Kubernetes manifests.

⚠️ If you DON'T know the exact image path:

  • Use search_images first to find the correct org/namespace

  • Or use find_image which tries multiple registries automatically

  • Check the project's GitHub repo for the correct image reference

Examples:

  • nginx → nginx:1.27.3

  • ghcr.io/kedacore/keda → ghcr.io/kedacore/keda:2.16.1

  • bitnami/redis → bitnami/redis:7.4.2

  • ghcr.io/autobrr/qui → ghcr.io/autobrr/qui:v0.3.0

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesImage reference (e.g., 'nginx', 'ghcr.io/owner/repo', 'bitnami/redis')
major_versionNoOnly consider tags with this major version (e.g., 3 for v3.x.x)
include_prereleaseNoInclude prerelease/RC versions (default: false)

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the transparency burden. It explains the tool returns a stable semantic version tag and gives examples, but doesn't clarify the ordering mechanism for 'latest' or behavior when no semver tag exists. Slight gap, but still good.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: concise first sentence, followed by usage guidance, warning block, and examples. Every sentence adds value, no fluff. Front-loaded with the main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the description implies the return type (a version string, used in Dockerfiles/Kubernetes). The examples illustrate the mapping from input to output, though they show full image:tag format which may cause slight confusion about the exact return value. Overall fairly complete given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema; 'major_version' and 'include_prerelease' are only documented in the schema, not in the description. No added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets the latest semantic version tag for a container image, specifying the output 'latest stable semantic version tag' and providing concrete examples. It distinguishes itself from siblings by noting when to use alternatives like search_images or find_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this when you KNOW the exact image path' and provides clear alternatives for when the path is unknown (search_images, find_image, checking GitHub). This leaves no ambiguity about usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_image_tagsA

List available tags for a container image.

Returns all semantic version tags for an image, sorted from newest to oldest. Useful when you need to see what versions are available or find a specific version pattern.

Can filter tags by regex pattern (e.g., '^v3\.' for v3.x versions only).

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesImage reference (e.g., 'nginx', 'ghcr.io/owner/repo')
limitNoMaximum number of tags to return (default: 20)
patternNoRegex pattern to filter tags (e.g., '^v3\.' or '^[0-9]+\.[0-9]+$')

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description fully responsible. Discloses read-only behavior, sorting, and filtering. Lacks details on error cases or pagination, but adequate for basic understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each informative and front-loaded. Efficiently conveys purpose and usage without excess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description explains return values (sorted tags) and filtering. Could be more explicit about output format, but overall covers key aspects for a list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds context about semantic version tags and regex filtering, adding some value beyond schema, but not significantly compensating.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'List available tags for a container image' with specific verb and resource. Differentiates from siblings like get_latest_image_tag by emphasizing it returns all tags sorted newest to oldest.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context: 'Useful when you need to see what versions are available or find a specific version pattern.' Mentions filtering by regex. Does not explicitly exclude or compare to alternatives, but context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_imagesA

Search for container images by name.

⚠️ USE THIS FIRST when you don't know the exact image path!

This searches Docker Hub and returns matching images with their full names. Use the results to find the correct org/namespace, then use find_image or get_latest_image_tag with the full path.

IMPORTANT: GitHub Container Registry (ghcr.io) has no search API. If you suspect an image is on GHCR, check the project's GitHub repo or documentation for the correct image path (usually ghcr.io/org/repo).

Examples:

  • "radarr" → finds linuxserver/radarr, hotio/radarr, etc.

  • "redis" → finds redis (official), bitnami/redis, etc.

  • "qui" → finds qompass/qui (but won't find ghcr.io/autobrr/qui - no GHCR search)

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results to return (default: 5)
queryYesSearch query (e.g., 'radarr', 'redis', 'postgres')

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that the tool searches Docker Hub, returns full names, and cannot search GHCR. It does not mention rate limits or read-only nature, but these are less critical for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections, emoji for emphasis, and examples. Every sentence adds value, though the content could be slightly more concise without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains that results include full image names. It covers the essential context for tool selection and usage. Missing details like pagination or result fields, but sufficient for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions and defaults. The description adds value through concrete examples showing how queries are interpreted (e.g., 'radarr' finds linuxserver/radarr, hotio/radarr), which aids understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches for container images by name, provides examples, and distinguishes from sibling tools like find_image and get_latest_image_tag. The emoji warning and explanation of when to use it make the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance to 'USE THIS FIRST' when image path is unknown, and to use find_image or get_latest_image_tag after obtaining the full name. Also warns about GHCR's lack of search API, directing to alternative approaches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedcheck_image_update
    • First observedfind_image
    • First observedget_latest_image_tag
    • First observedlist_image_tags
    • First observedsearch_images

TDQS

A4.4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a distinct purpose: searching for images, finding exact paths, getting latest tags, listing tags, and checking for updates. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case, e.g., search_images, get_latest_image_tag. Clear and predictable.

Tool Count5/5

With 5 tools covering search, discovery, tag retrieval, listing, and update checking, the count is ideal for the domain. Not excessive or insufficient.

Completeness5/5

The tool set provides a complete workflow: discover images, locate correct paths, get latest version, list all tags, and check for updates. No obvious gaps for a tag-finding utility.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Enables users to interact with container registries through the ORAS CLI, providing information about container images, platforms, and signatures via natural language queries.
    7
    Apache 2.0
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables LLMs to search Docker Hub repositories, discover container images, and manage Docker Hub repositories and tags through natural language queries. Supports both public content access and authenticated operations with Docker Personal Access Tokens.
    163
    Apache 2.0
  • A
    license
    A
    quality
    A
    maintenance
    Enables AI coding agents to retrieve the latest stable versions of packages and tools across multiple ecosystems, preventing outdated dependency versions in generated code.
    4
    8
    Apache 2.0