What is Ocireg Mcp

ocireg-mcp is an MCP (Model Context Protocol) server that provides tools for querying OCI registries and image references, enabling LLM-powered applications to interact with container images.

Use cases

Use cases for ocireg-mcp include querying image details for CI/CD pipelines, managing container deployments, and integrating image information into LLM-powered applications.

How to use

To use ocireg-mcp, you need to set up the server with the required prerequisites, including Go 1.21 or later. You can authenticate using a bearer token, username and password, or Docker config. Once set up, you can use tools like get_image_info, list_tags, get_image_manifest, and get_image_config to retrieve information about OCI images.

Key features

Key features of ocireg-mcp include retrieving information about OCI images, listing tags for repositories, obtaining image manifests, and accessing image configurations.

Where to use

ocireg-mcp can be used in various fields such as DevOps, cloud computing, and container management, where interaction with OCI registries is necessary.

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://github.com/stacklok/toolhive#installation

# Enable auto-discovery to automatically configure supported clients
thv config auto-discovery true

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

1. Bearer Token: Set the following environment variable:

   • OCI_TOKEN: Bearer token for registry authentication

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

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

3. Docker Config: If no token or username/password is provided, the server will use the default Docker keychain, which reads credentials from ~/.docker/config.json.

Examples:

# Bearer token authentication
export OCI_TOKEN=mytoken

# Username/password authentication
export OCI_USERNAME=myuser
export OCI_PASSWORD=mypassword

Port Configuration

The server can be configured to listen on a specific port using either:

1. Environment Variable:

   • MCP_PORT: The port number to listen on (must be between 0 and 65535)
   • If not set or invalid, defaults to port 8080

2. Command-line Flag:

   • -port: Overrides the environment variable setting (must be between 0 and 65535)
   • If invalid port provided it defaults to port 8080
   • Example: ./ocireg-mcp -port 9090

Testing

go test ./...

Linting

golangci-lint run

## Contributing

We welcome contributions to this MCP server! If you'd like to contribute, please review
the [CONTRIBUTING guide](https://github.com/StacklokLabs/ocireg-mcp/blob/master/CONTRIBUTING.md) for details on how to get started.

If you run into a bug or have a feature request, please
[open an issue](https://github.com/StacklokLabs/ocireg-mcp/issues) in the
repository or join us in the `#mcp-servers` channel on our
[community Discord server](https://discord.gg/stacklok).

## License

This project is licensed under the Apache v2 License - see the LICENSE file for details.