gem-hunter

Docker MCP Plugin and Docker MCP Gateway

What is MCP?

Overview

Features

Installation

Prerequisites

Install as Docker CLI Plugin

# Clone the repository
git clone https://github.com/docker/mcp-gateway.git
cd mcp-gateway
mkdir -p "$HOME/.docker/cli-plugins/"

# Build and install the plugin
make docker-mcp

docker mcp --help

Usage

Note

Running without Docker Desktop Feature Flags

If you encounter "Docker Desktop is not running" errors when the Docker daemon is active, you can bypass Desktop feature checks by setting:

export DOCKER_MCP_IN_CONTAINER=1

This is useful when running in WSL2, containerized environments, or Docker CE where Desktop backend sockets are unavailable.

Note

Enabling Profiles outside Docker Desktop

Profiles are enabled automatically in Docker Desktop. If you are using the CLI independently (e.g. Docker CE, WSL2, or a containerized environment), enable the profiles feature first:

docker mcp feature enable profiles

Profile Management

# Make sure to `docker mcp catalog pull mcp/docker-mcp-catalog` first.

# Create a new profile
docker mcp profile create --name dev-tools \
  --server catalog://mcp/docker-mcp-catalog/github

# Create a profile and connect it to a client
docker mcp profile create --name dev-tools \
  --server catalog://mcp/docker-mcp-catalog/github \
  --connect cursor

# List all profiles
docker mcp profile list

# Show profile details
docker mcp profile show <profile-id>

# Remove a profile
docker mcp profile remove <profile-id>

# Export/import profiles
docker mcp profile export <profile-id> output.yaml
docker mcp profile import input.yaml

# Push/pull profiles to OCI registries
docker mcp profile push <profile-id> <oci-reference>
docker mcp profile pull <oci-reference>

Manage servers in a profile

# List servers across all profiles
docker mcp profile server ls

# Filter servers by name or profile
docker mcp profile server ls --filter name=github
docker mcp profile server ls --filter profile=dev-tools

# Add servers to a profile
docker mcp profile server add dev-tools \
  --server catalog://mcp/docker-mcp-catalog/notion

# Remove servers from a profile
docker mcp profile server remove dev-tools github slack

Configure servers in a profile

# Set configuration values (<server-name>.<config-key>=<value>)
docker mcp profile config <profile-id> --set github.timeout=30

# Get configuration values (<server-name>.<config-key>)
docker mcp profile config <profile-id> --get github.timeout

# Get all configuration
docker mcp profile config <profile-id> --get-all

# Delete configuration values (<server-name>.<config-key>)
docker mcp profile config <profile-id> --del github.timeout

Manage tool allowlists in a profile

# Enable specific tools (dot notation: <server>.<tool>)
docker mcp profile tools <profile-id> --enable github.create_issue --enable github.list_repos

# Disable specific tools
docker mcp profile tools <profile-id> --disable github.search_code

# Enable/disable all tools for a server
docker mcp profile tools <profile-id> --enable-all github
docker mcp profile tools <profile-id> --disable-all github

Catalog Management

# List catalogs
docker mcp catalog ls

# Show a catalog
docker mcp catalog show <oci-reference>

# Create a catalog from server references
docker mcp catalog create myorg/catalog:latest --title "My Catalog" \
  --server catalog://mcp/docker-mcp-catalog/github \
  --server file://./my-server.yaml

# Create a catalog from an existing profile
docker mcp catalog create myorg/catalog:latest --from-profile dev-tools

# Create a catalog from the community registry
docker mcp catalog create myorg/catalog:latest \
  --from-community-registry registry.modelcontextprotocol.io

# Push/pull catalogs to OCI registries
docker mcp catalog push <oci-reference>
docker mcp catalog pull <oci-reference>

# Manage servers within a catalog
docker mcp catalog server ls <oci-reference>
docker mcp catalog server add <oci-reference> --server docker://my-server:latest
docker mcp catalog server remove <oci-reference> github
docker mcp catalog server inspect <oci-reference> <server-name>

# Remove a catalog
docker mcp catalog remove <oci-reference>

# Tag a catalog
docker mcp catalog tag <source>:<tag> <target>:<tag>

MCP Gateway Operations

# Run the MCP gateway (stdio, using the default profile)
docker mcp gateway run

# Run with a specific profile
docker mcp gateway run --profile dev-tools

# Run the MCP gateway (streaming)
docker mcp gateway run --port 8080 --transport streaming

Client Connection

# List client configurations
docker mcp client ls

# Connect a client to a profile
docker mcp client connect <client-name> --profile <profile-id>

# Disconnect from a client
docker mcp client disconnect <client-name>

Secrets and OAuth

# Manage secrets
docker mcp secret --help

# Handle OAuth flows
docker mcp oauth --help

# export any desktop secrets needed by either server1 or server2
#   (temporary requirement to export secrets for docker cloud runs - this command
#    will no longer be required once Docker Cloud can access secret stores)
docker mcp secret export server1 server2

Tool Management

# Count available tools
docker mcp tools count

# List all available MCP tools
docker mcp tools ls

# List all available MCP tools in JSON format
docker mcp tools ls --format=json

# Inspect a specific tool
docker mcp tools inspect <tool-name>

# Call a tool with arguments
docker mcp tools call <tool-name> [arguments...]

# Enable/disable tools for a server in a profile
docker mcp profile tools <profile-id> --enable <server>.<tool>
docker mcp profile tools <profile-id> --disable <server>.<tool>

Configuration

Environment Variables

# Set custom Claude Code configuration directory
export CLAUDE_CONFIG_DIR=/path/to/custom/config

# Connect MCP Gateway to Claude Code
docker mcp client connect claude-code --profile dev-tools --global

# Claude Code will now use /path/to/custom/config/.claude.json

Architecture

AI Client → MCP Gateway → MCP Servers (Docker Containers)

Contributing

License

Support