OCI Registry MCP Server

1# OCI Registry MCP Server
2 
3[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/StacklokLabs/ocireg-mcp)](https://archestra.ai/mcp-catalog/stackloklabs__ocireg-mcp)
4An MCP (Model Context Protocol) server that provides tools for querying OCI
5registries and image references.
6 
7## Overview
8 
9This project implements an SSE-based MCP server that allows LLM-powered
10applications to interact with OCI registries. It provides tools for retrieving
11information about container images, listing tags, and more.
12 
13## Features
14 
15- Get information about OCI images
16- List tags for repositories
17- Get image manifests
18- Get image configs
19 
20## MCP Tools
21 
22The server provides the following MCP tools:
23 
24### get_image_info
25 
26Get information about an OCI image.
27 
28**Input:**
29 
30- `image_ref`: The image reference (e.g., docker.io/library/alpine:latest)
31 
32**Output:**
33 
34- Image information including digest, size, architecture, OS, creation date, and
35  number of layers
36 
37### list_tags
38 
39List tags for a repository.
40 
41**Input:**
42 
43- `repository`: The repository name (e.g., docker.io/library/alpine)
44 
45**Output:**
46 
47- List of tags for the repository
48 
49### get_image_manifest
50 
51Get the manifest for an OCI image.
52 
53**Input:**
54 
55- `image_ref`: The image reference (e.g., docker.io/library/alpine:latest)
56 
57**Output:**
58 
59- The image manifest
60 
61### get_image_config
62 
63Get the config for an OCI image.
64 
65**Input:**
66 
67- `image_ref`: The image reference (e.g., docker.io/library/alpine:latest)
68 
69**Output:**
70 
71- The image config
72 
73## Usage
74 
75### Running with ToolHive (Recommended)
76 
77The easiest way to run the OCI Registry MCP server is using
78[ToolHive](https://github.com/stacklok/toolhive), which provides secure,
79containerized deployment of MCP servers:
80 
81```bash
82# Install ToolHive (if not already installed)
83# See: https://docs.stacklok.com/toolhive/guides-cli/install
84 
85# Register a supported client so ToolHive can auto-configure your environment
86thv client setup
87# Run the OCI Registry MCP server (packaged as 'oci-registry' in ToolHive)
88thv run oci-registry
89 
90# List running servers
91thv list
92 
93# Get detailed information about the server
94thv registry info oci-registry
95```
96 
97The server will be available to your MCP-compatible clients and can query OCI
98registries for image information.
99 
100#### Authentication with ToolHive
101 
102If you need to access private registries, you can provide authentication
103credentials using ToolHive's secret management:
104 
105```bash
106# For bearer token authentication
107thv secret set oci-token
108# Enter your bearer token when prompted
109 
110thv run --secret oci-token,target=OCI_TOKEN oci-registry
111 
112# For username/password authentication
113thv secret set oci-username
114thv secret set oci-password
115# Enter your credentials when prompted
116 
117thv run --secret oci-username,target=OCI_USERNAME --secret oci-password,target=OCI_PASSWORD oci-registry
118```
119 
120## Development
121 
122### Prerequisites
123 
124- Go 1.21 or later
125- Access to OCI registries
126 
127### Authentication
128 
129The server supports the following authentication methods for accessing private
130OCI registries (in order of priority):
131 
1321. **HTTP Authorization Header** (Highest Priority): Include a bearer token in
133   the HTTP request's `Authorization` header:
134 
135   - `Authorization: Bearer <your-token>`
136   - This method takes precedence over all other authentication methods
137   - When present, environment variables and Docker config are ignored
138 
1392. **Bearer Token Environment Variable**: Set the following environment variable:
140 
141   - `OCI_TOKEN`: Bearer token for registry authentication
142 
1433. **Username and Password**: Set the following environment variables:
144 
145   - `OCI_USERNAME`: Username for registry authentication
146   - `OCI_PASSWORD`: Password for registry authentication
147 
1484. **Docker Config** (Lowest Priority): If no other authentication is provided,
149   the server will use the default Docker keychain, which reads credentials from
150   `~/.docker/config.json`.
151 
152Examples:
153 
154```bash
155# HTTP Authorization header (for per-request authentication)
156# This is handled automatically by the MCP client when making requests
157# Example: curl -H "Authorization: Bearer mytoken" http://localhost:8080/...
158 
159# Bearer token authentication via environment variable
160export OCI_TOKEN=mytoken
161 
162# Username/password authentication via environment variables
163export OCI_USERNAME=myuser
164export OCI_PASSWORD=mypassword
165```
166 
167### Port Configuration
168 
169The server can be configured to listen on a specific port using either:
170 
1711. **Environment Variable**:
172 
173   - `MCP_PORT`: The port number to listen on (must be between 0 and 65535)
174   - If not set or invalid, defaults to port 8080
175 
1762. **Command-line Flag**:
177   - `-port`: Overrides the environment variable setting (must be between 0
178     and 65535)
179   - If invalid port provided it defaults to port 8080
180   - Example: `./ocireg-mcp -port 9090`
181 
182### Testing
183 
184```bash
185go test ./...
186```
187 
188### Linting
189 
190```bash
191golangci-lint run
192```
193 
194## Contributing
195 
196We welcome contributions to this MCP server! If you'd like to contribute, please
197review the [CONTRIBUTING guide](./CONTRIBUTING.md) for details on how to get
198started.
199 
200If you run into a bug or have a feature request, please
201[open an issue](https://github.com/StacklokLabs/ocireg-mcp/issues) in the
202repository or join us in the `#mcp-servers` channel on our
203[community Discord server](https://discord.gg/stacklok).
204 
205## License
206 
207This project is licensed under the Apache v2 License - see the LICENSE file for
208details.
209