https://github.com/stackloklabs/ocireg-mcp
An MCP (Model Context Protocol) server that provides tools for querying OCI registries and image references.
https://github.com/stackloklabs/ocireg-mcp
Last synced: 4 months ago
JSON representation
An MCP (Model Context Protocol) server that provides tools for querying OCI registries and image references.
- Host: GitHub
- URL: https://github.com/stackloklabs/ocireg-mcp
- Owner: StacklokLabs
- License: apache-2.0
- Created: 2025-05-06T07:51:01.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-06-17T07:48:42.000Z (4 months ago)
- Last Synced: 2025-06-17T08:37:12.676Z (4 months ago)
- Language: Go
- Size: 62.5 KB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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](https://github.com/stacklok/toolhive), which provides secure, containerized deployment of MCP servers:
```bash
# 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:
```bash
# 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:
```bash
# 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
```bash
go test ./...
```
### Linting
```bash
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.