OCI Registry MCP Server

An MCP (Model Context Protocol) server that provides tools for querying OCI registries and image references.

Overview

This project implements an SSE-based MCP server that allows LLM-powered applications to interact with OCI registries. It provides tools for retrieving information about container images, listing tags, and more.

Features

• Get information about OCI images
• List tags for repositories
• Get image manifests
• Get image configs

MCP Tools

The server provides the following MCP tools:

get_image_info

Get information about an OCI image.

Input:

• image_ref: The image reference (e.g., docker.io/library/alpine:latest)

Output:

• Image information including digest, size, architecture, OS, creation date, and number of layers

list_tags

List tags for a repository.

Input:

• repository: The repository name (e.g., docker.io/library/alpine)

Output:

• List of tags for the repository

get_image_manifest

Get the manifest for an OCI image.

Input:

• image_ref: The image reference (e.g., docker.io/library/alpine:latest)

Output:

• The image manifest

get_image_config

Get the config for an OCI image.

Input:

• image_ref: The image reference (e.g., docker.io/library/alpine:latest)

Output:

• The image config

Usage

Running with ToolHive (Recommended)

The easiest way to run the OCI Registry MCP server is using ToolHive, which provides secure, containerized deployment of MCP servers:

# Install ToolHive (if not already installed)
# See: https://docs.stacklok.com/toolhive/guides-cli/install

# Register a supported client so ToolHive can auto-configure your environment
thv client setup
# Run the OCI Registry MCP server (packaged as 'oci-registry' in ToolHive)
thv run oci-registry

# List running servers
thv list

# Get detailed information about the server
thv registry info oci-registry

The server will be available to your MCP-compatible clients and can query OCI registries for image information.

Authentication with ToolHive

If you need to access private registries, you can provide authentication credentials using ToolHive's secret management:

# For bearer token authentication
thv secret set oci-token
# Enter your bearer token when prompted

thv run --secret oci-token,target=OCI_TOKEN oci-registry

# For username/password authentication
thv secret set oci-username
thv secret set oci-password
# Enter your credentials when prompted

thv run --secret oci-username,target=OCI_USERNAME --secret oci-password,target=OCI_PASSWORD oci-registry

Development

Prerequisites

• Go 1.21 or later
• Access to OCI registries

Authentication

The server supports the following authentication methods for accessing private OCI registries (in order of priority):

1. HTTP Authorization Header (Highest Priority): Include a bearer token in the HTTP request's Authorization header:

   • Authorization: Bearer <your-token>
   • This method takes precedence over all other authentication methods
   • When present, environment variables and Docker config are ignored

2. Bearer Token Environment Variable: Set the following environment variable:

   • OCI_TOKEN: Bearer token for registry authentication

3. Username and Password: Set the following environment variables:

   • OCI_USERNAME: Username for registry authentication
   • OCI_PASSWORD: Password for registry authentication

4. Docker Config (Lowest Priority): If no other authentication is provided, the server will use the default Docker keychain, which reads credentials from ~/.docker/config.json.

Examples:

# HTTP Authorization header (for per-request authentication)
# This is handled automatically by the MCP client 

... [View full README on GitHub](https://github.com/StacklokLabs/ocireg-mcp#readme)