Skip to main content
Glama
container-tag-finder

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.

Inputs: image (required), current_tag (required).

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

Inputs: name (required).

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

Inputs: image (required), major_version, include_prerelease.

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).

Inputs: image (required), limit, pattern.

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)

Inputs: query (required), limit.

Tool Schema Changelog

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

Loading tool schema changelog…

    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 recent community 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
      C
      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.
      171
      Apache 2.0
    • A
      license
      A
      quality
      B
      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
      187 PyPI
      9
      Apache 2.0