The OCI Registry MCP server provides tools to interact with Oracle Cloud Infrastructure Container Registry (OCIR) resources, enabling management of container repositories.
Installation
uvx oracle.oci-registry-mcp-server
Running the Server
STDIO Transport Mode
uvx oracle.oci-registry-mcp-server
HTTP Streaming Transport Mode
ORACLE_MCP_HOST=<hostname/IP address> ORACLE_MCP_PORT=<port number> uvx oracle.oci-registry-mcp-server
| Tool Name | Description |
|---|
create_container_repository | Create a new container repository |
list_container_repositories | List container repositories in a given compartment |
get_container_repo_details | Get details for a specific container repository |
delete_container_repository | Delete a container repository |
Usage Examples
List Repositories
List all container repositories in my compartment
Create a Repository
Create a container repository named "myapp/backend"
Create a private repository named "myapp/frontend" in compartment ocid1.compartment.oc1..example
Get Repository Details
Show me details for repository "myapp/backend"
- Repository name and OCID
- Public/private visibility
- Image count
- Created/updated timestamps
- Immutability settings
Delete a Repository
Delete container repository "old-app/service"
Destructive ActionDeleting a repository permanently removes all contained images. Ensure images are backed up or no longer needed before deletion.
Understanding OCI Container Registry
What is OCIR?
Oracle Cloud Infrastructure Registry (OCIR) is a fully managed Docker v2 container registry:
- Store Container Images - Docker and OCI-compliant images
- Private or Public - Control image visibility
- Integrated - Works seamlessly with OKE, Compute, Functions
- Geo-Replicated - Available in all OCI regions
- Secure - Encrypted at rest and in transit
Key Concepts
Repository
- Logical collection of related container images
- Unique name within tenancy/compartment
- Can be public or private
- Contains multiple image versions (tags)
Image
- Container image stored in a repository
- Identified by digest (SHA256 hash)
- Can have multiple tags
- Immutable once pushed (digest never changes)
Tag
- Human-readable alias for an image
- Points to specific image digest
- Can be reassigned to different images
- Common patterns: latest, v1.0, staging, commit-hash
Registry Endpoint
Format: <region-key>.ocir.io/<tenancy-namespace>/<repository-name>:<tag>
Example: phx.ocir.io/mytenancy/myapp/backend:latest
Repository Types
Private (Default)
- Requires authentication to pull
- Access controlled by IAM policies
- Recommended for proprietary applications
Public
- Anyone can pull images
- No authentication required for pulls
- Useful for open-source projects
- Still requires auth for pushes
Image Immutability
When enabled:
- Images cannot be overwritten
- Tags cannot be reassigned
- Prevents accidental or malicious changes
- Ensures reproducibility
Authentication for Docker
To push/pull images from OCIR:
Get Auth Token
# Create auth token via Identity service
oci iam auth-token create --user-id <user-ocid> --description "OCIR access"
Docker Login
docker login <region>.ocir.io
Username: <tenancy-namespace>/<username>
Password: <auth-token>
docker login phx.ocir.io
Username: mytenancy/oracleidentitycloudservice/[email protected]
Password: <auth-token>
Working with Images
Push an Image
# Tag image with OCIR path
docker tag myapp:latest phx.ocir.io/mytenancy/myapp/backend:latest
# Push to OCIR
docker push phx.ocir.io/mytenancy/myapp/backend:latest
Pull an Image
# Pull from OCIR
docker pull phx.ocir.io/mytenancy/myapp/backend:latest
List Images in Repository
Use OCI Console or CLI to view images:
oci artifacts container image list --compartment-id <compartment-ocid> --repository-name myapp/backend
Required Permissions
Your OCI user or instance principal needs these IAM permissions:
Read Repositories:
Allow group RegistryReaders to read repos in compartment MyCompartment
Allow group RegistryAdmins to manage repos in compartment MyCompartment
Allow group Developers to read repos in compartment MyCompartment
Allow group Developers to manage repos in compartment MyCompartment where any {request.operation='CreateContainerImageSignature', request.operation='DeleteContainerImage', request.operation='DeleteContainerImageSignature'}
Security NoticeAll actions are performed with the permissions of the configured OCI CLI profile. We advise:
- Least-privilege IAM setup
- Secure credential management (auth tokens)
- Rotate auth tokens regularly
- Use private repositories for sensitive images
- Enable image scanning for vulnerabilities
- Never expose auth tokens in logs
Common Use Cases
CI/CD Integration
- Build container images in CI pipeline
- Push images to OCIR
- Tag images with build/commit info
- Deploy from OCIR to OKE or Compute
Kubernetes Deployments
- Store application images in OCIR
- Configure OKE image pull secrets
- Deploy pods from OCIR images
- Implement rolling updates
Multi-Environment Management
- Separate repos for dev/test/prod
- Use tags for environment promotion
- Maintain image lineage
- Control access per environment
Microservices Architecture
- One repository per service
- Version independently
- Deploy services individually
- Manage service dependencies
Best Practices
Repository Naming
- Use descriptive names:
application/component
- Include organization:
team/application/component
- Keep names lowercase
- Use hyphens, not underscores
- Avoid special characters
Tagging Strategy
- Use semantic versioning:
v1.2.3
- Include build info:
v1.2.3-build.456
- Tag with git commit:
abc123f
- Maintain
latest tag
- Never reuse tags (or enable immutability)
Security
- Use private repositories by default
- Enable image scanning
- Sign images for verification
- Rotate auth tokens regularly
- Use short-lived tokens in CI/CD
- Audit repository access
Image Management
- Tag images with multiple aliases
- Clean up old images regularly
- Enable image retention policies
- Document image contents
- Scan for vulnerabilities
- Use region-local registry
- Minimize image layers
- Optimize image sizes
- Use multi-stage builds
- Cache base layers
Troubleshooting
Cannot Push Images
Authentication fails:
- Verify auth token is valid
- Check username format:
<namespace>/<username>
- Ensure token hasn’t expired
- Confirm IAM permissions
Repository not found:
- Create repository first via API or console
- Verify repository name is correct
- Check compartment
Cannot Pull Images
Private repository:
- Authenticate with docker login
- Verify read permissions
- Check repository exists
Public repository:
- Verify repository is actually public
- Check image/tag exists
Slow Push/Pull
- Use geographically close region
- Check network bandwidth
- Reduce image size
- Optimize layers
Repository Deletion Fails
- Repository must be empty (no images)
- Delete all images first
- Verify permissions
- Check for retention policies
Integration with OKE
Create Image Pull Secret
kubectl create secret docker-registry ocir-secret \
--docker-server=<region>.ocir.io \
--docker-username='<tenancy-namespace>/<username>' \
--docker-password='<auth-token>' \
--docker-email='<email>'
Use in Pod Spec
apiVersion: v1
kind: Pod
metadata:
name: myapp
spec:
containers:
- name: backend
image: phx.ocir.io/mytenancy/myapp/backend:latest
imagePullSecrets:
- name: ocir-secret
Additional Resources
