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](./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.