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

Run with Docker Compose (Recommended)

# 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:

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