container-tag-finder
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., "@container-tag-finderwhat is the latest tag for nginx?"
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.
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/nginxRun the MCP server via Docker
# Interactive mode for MCP
docker compose run --rm mcpLocal 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.serverThe 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.,16for 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 referencepattern(query) - Regex filterlimit(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 referencelist_image_tags
List available tags for an image.
Input: { "image": "postgres", "pattern": "^16\\." }
Output: All PostgreSQL 16.x tagscheck_image_update
Check if an update is available.
Input: { "image": "nginx", "current_tag": "1.25.0" }
Output: Update status and recommendationSupported Registries
Docker Hub (
docker.io) - Official and user imagesGitHub 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 |
| docker.io | library/nginx |
| docker.io | bitnami/redis |
| ghcr.io | owner/repo |
| quay.io | prometheus/prometheus |
| gcr.io | project/image |
Version Detection
The API parses semantic versions from tags intelligently:
Standard semver:
1.2.3,v1.2.3With prerelease:
1.2.3-rc1,1.2.3-beta.2With build metadata:
1.2.3+build123Variant suffixes:
1.2.3-alpine,1.2.3-slim(treated as prerelease)Two-part versions:
1.2(treated as1.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:
Asking "what's the latest nginx version?" leads to web searches with outdated results
Agents can't easily query container registries directly
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 toolscheck_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.
| Name | Required | Description | Default |
|---|---|---|---|
| image | Yes | Image reference (e.g., 'nginx', 'ghcr.io/owner/repo') | |
| current_tag | Yes | The current tag being used (e.g., '1.25.0', 'v2.10.0') |
TDQS
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.
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.
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.
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.
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.
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"):
First check the project's GitHub/website to find the correct image path
Look for org/repo pattern (e.g., "autobrr/qui" not just "qui")
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
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Image name. Use 'org/repo' format for best results (e.g., 'autobrr/qui', 'linuxserver/radarr') |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| image | Yes | Image reference (e.g., 'nginx', 'ghcr.io/owner/repo', 'bitnami/redis') | |
| major_version | No | Only consider tags with this major version (e.g., 3 for v3.x.x) | |
| include_prerelease | No | Include prerelease/RC versions (default: false) |
TDQS
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.
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.
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.
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.
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.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| image | Yes | Image reference (e.g., 'nginx', 'ghcr.io/owner/repo') | |
| limit | No | Maximum number of tags to return (default: 20) | |
| pattern | No | Regex pattern to filter tags (e.g., '^v3\.' or '^[0-9]+\.[0-9]+$') |
TDQS
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.
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.
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.
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.
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.
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)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (default: 5) | |
| query | Yes | Search query (e.g., 'radarr', 'redis', 'postgres') |
TDQS
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.
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.
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.
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.
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.
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.
5 tool updates
v0.1.0- First observed
check_image_update - First observed
find_image - First observed
get_latest_image_tag - First observed
list_image_tags - First observed
search_images
TDQS
Scored across 5 tools
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.
All tool names follow a consistent verb_noun pattern in snake_case, e.g., search_images, get_latest_image_tag. Clear and predictable.
With 5 tools covering search, discovery, tag retrieval, listing, and update checking, the count is ideal for the domain. Not excessive or insufficient.
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
Related MCP Connectors
Versioned documentation registry and semantic search for AI tools and coding assistants.
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.
npm & PyPI freshness for AI agents: latest version, deprecations, dated breaking-change diffs.
AI Agent Source Registry. 288K+ curated sources for agentic search and discovery.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables users to interact with container registries through the ORAS CLI, providing information about container images, platforms, and signatures via natural language queries.7Apache 2.0

Docker Hub MCP Serverofficial
AlicenseNot gradedqualityDmaintenanceEnables 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.163Apache 2.0- AlicenseAqualityAmaintenanceEnables AI coding agents to retrieve the latest stable versions of packages and tools across multiple ecosystems, preventing outdated dependency versions in generated code.48Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to search, analyze, and manage Docker images on Docker Hub through standardized MCP tools, with features including security scanning, layer analysis, and image comparison.-