Skip to content
Back to search

mcp-gateway

docker mcp CLI plugin / MCP Gateway

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/docker--mcp-gateway/badge.svg)](/listings/docker--mcp-gateway)

HTML

<a href="/listings/docker--mcp-gateway"><img src="/api/listings/docker--mcp-gateway/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Docker Desktop `4.59+` (with MCP Toolkit feature enabled)

<div align="left"> </div> - Go 1.24+ (for development)

Install as Docker CLI Plugin

The MCP cli will already be installed on recent versions of Docker Desktop but you can build and install the latest version by following these steps:

# 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

After installation, the plugin will be available as:

docker mcp --help

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 343 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Docker MCP Plugin and Docker MCP Gateway
  2. ![build](https://github.com/docker/mcp-gateway/actions/workflows/ci.yml/badge.svg)
  3. The [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/), in Docker Desktop, allows
  4. developers to configure and consume MCP servers from the [Docker MCP Catalog](https://hub.docker.com/mcp).
  5. Underneath, the Toolkit is powered by a docker CLI plugin: `docker-mcp`. This repository is the code of this CLI plugin. It can work in Docker Desktop or independently.
  6. The main feature of this CLI is the **Docker MCP Gateway** which allows easy and secure running and deployment of MCP servers. See [Features](#Features) for a list of all the features.
  7. ## What is MCP?
  8. The [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) is an open protocol that standardizes how AI applications connect to external data sources and tools. It provides a secure, controlled way for language models to access and interact with various services, databases, and APIs.
  9. ## Overview
  10. Developers face criticial barriers when integrating Model Context Protocol (MCP) tools into production workflows:
  11. - **Managing MCP server lifecycle** Each local MCP sever in the catalog runs in an isolated Docker container. npx and uvx servers are granted minimal host privileges.
  12. - **Providing a unified interface** AI models access MCP servers through a single Gateway.
  13. - **Handling authentication and security** Keep secrets out of environment variables using Docker Desktop's secrets management.
  14. - **Supports dynamic tool discovery** and configuration. Each MCP client (eg VS Code, Cursor, Claude Desktop, etc.) connects to the same Gateway configuration, ensuring consistency across different clients.
  15. - **Enables OAuth flows** for MCPs that require OAuth access token service connections.
  16. ## Features
  17. - 🐳 **Container-based Servers**: Run MCP servers as Docker containers with proper isolation.
  18. - 🔧 **Server Management**: List, inspect, and call MCP tools, resources and prompts from multiple servers.
  19. - 🔐 **Secrets Management**: Secure handling of API keys and credentials via Docker Desktop.
  20. - 🌐 **OAuth Integration**: Built-in OAuth flows for service authentication.
  21. - 📋 **Server Catalog**: Manage and configure multiple MCP catalogs.
  22. - 🔍 **Dynamic Discovery**: Automatic tool, prompt, and resource discovery from running servers.
  23. - 📊 **Monitoring**: Built-in logging and call tracing capabilities.
  24. ## Installation
  25. ### Prerequisites
  26. - Docker Desktop `4.59+` (with MCP Toolkit feature enabled)
  27. <div align="left">
  28. <img src="./img/enable_toolkit.png" width="400"/>
  29. </div>
  30. - Go 1.24+ (for development)
  31. ### Install as Docker CLI Plugin
  32. The MCP cli will already be installed on recent versions of Docker Desktop but you can build and install the latest version by following these steps:
  33. ```bash
  34. # Clone the repository
  35. git clone https://github.com/docker/mcp-gateway.git
  36. cd mcp-gateway
  37. mkdir -p "$HOME/.docker/cli-plugins/"
  38. # Build and install the plugin
  39. make docker-mcp
  40. ```
  41. After installation, the plugin will be available as:
  42. ```bash
  43. docker mcp --help
  44. ```
  45. ## Usage
  46. > [!NOTE]
  47. > **Running without Docker Desktop Feature Flags**
  48. >
  49. > If you encounter "Docker Desktop is not running" errors when the Docker daemon is active, you can bypass Desktop feature checks by setting:
  50. > ```bash
  51. > export DOCKER_MCP_IN_CONTAINER=1
  52. > ```
  53. > This is useful when running in WSL2, containerized environments, or Docker CE where Desktop backend sockets are unavailable.
  54. > [!NOTE]
  55. > **Enabling Profiles outside Docker Desktop**
  56. >
  57. > 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:
  58. > ```bash
  59. > docker mcp feature enable profiles
  60. > ```
  61. ### Profile Management
  62. Servers are organized into **profiles**. A profile groups related MCP servers together and can be connected to clients, exported, and shared via OCI registries.
  63. Servers in a profile can reference multiple sources:
  64. - **Catalog references**: `catalog://mcp/docker-mcp-catalog/github`
  65. - **OCI image references**: `docker://my-server:latest`
  66. - **MCP Registry references**: `https://registry.modelcontextprotocol.io/v0/servers/<id>`
  67. - **Local file references**: `file://./server.yaml`
  68. ```bash
  69. # Make sure to `docker mcp catalog pull mcp/docker-mcp-catalog` first.
  70. # Create a new profile
  71. docker mcp profile create --name dev-tools \
  72. --server catalog://mcp/docker-mcp-catalog/github
  73. # Create a profile and connect it to a client
  74. docker mcp profile create --name dev-tools \
  75. --server catalog://mcp/docker-mcp-catalog/github \
  76. --connect cursor
  77. # List all profiles
  78. docker mcp profile list
  79. # Show profile details
  80. docker mcp profile show <profile-id>
  81. # Remove a profile
  82. docker mcp profile remove <profile-id>
  83. # Export/import profiles
  84. docker mcp profile export <profile-id> output.yaml
  85. docker mcp profile import input.yaml
  86. # Push/pull profiles to OCI registries
  87. docker mcp profile push <profile-id> <oci-reference>
  88. docker mcp profile pull <oci-reference>
  89. ```
  90. #### Manage servers in a profile
  91. ```bash
  92. # List servers across all profiles
  93. docker mcp profile server ls
  94. # Filter servers by name or profile
  95. docker mcp profile server ls --filter name=github
  96. docker mcp profile server ls --filter profile=dev-tools
  97. # Add servers to a profile
  98. docker mcp profile server add dev-tools \
  99. --server catalog://mcp/docker-mcp-catalog/notion
  100. # Remove servers from a profile
  101. docker mcp profile server remove dev-tools github slack
  102. ```
  103. #### Configure servers in a profile
  104. ```bash
  105. # Set configuration values (<server-name>.<config-key>=<value>)
  106. docker mcp profile config <profile-id> --set github.timeout=30
  107. # Get configuration values (<server-name>.<config-key>)
  108. docker mcp profile config <profile-id> --get github.timeout
  109. # Get all configuration
  110. docker mcp profile config <profile-id> --get-all
  111. # Delete configuration values (<server-name>.<config-key>)
  112. docker mcp profile config <profile-id> --del github.timeout
  113. ```
  114. #### Manage tool allowlists in a profile
  115. ```bash
  116. # Enable specific tools (dot notation: <server>.<tool>)
  117. docker mcp profile tools <profile-id> --enable github.create_issue --enable github.list_repos
  118. # Disable specific tools
  119. docker mcp profile tools <profile-id> --disable github.search_code
  120. # Enable/disable all tools for a server
  121. docker mcp profile tools <profile-id> --enable-all github
  122. docker mcp profile tools <profile-id> --disable-all github
  123. ```
  124. ### Catalog Management
  125. Manage the OCI-based catalogs available to the MCP gateway. The [default catalog](https://hub.docker.com/mcp) is the image `mcp/docker-mcp-catalog`.
  126. ```bash
  127. # List catalogs
  128. docker mcp catalog ls
  129. # Show a catalog
  130. docker mcp catalog show <oci-reference>
  131. # Create a catalog from server references
  132. docker mcp catalog create myorg/catalog:latest --title "My Catalog" \
  133. --server catalog://mcp/docker-mcp-catalog/github \
  134. --server file://./my-server.yaml
  135. # Create a catalog from an existing profile
  136. docker mcp catalog create myorg/catalog:latest --from-profile dev-tools
  137. # Create a catalog from the community registry
  138. docker mcp catalog create myorg/catalog:latest \
  139. --from-community-registry registry.modelcontextprotocol.io
  140. # Push/pull catalogs to OCI registries
  141. docker mcp catalog push <oci-reference>
  142. docker mcp catalog pull <oci-reference>
  143. # Manage servers within a catalog
  144. docker mcp catalog server ls <oci-reference>
  145. docker mcp catalog server add <oci-reference> --server docker://my-server:latest
  146. docker mcp catalog server remove <oci-reference> github
  147. docker mcp catalog server inspect <oci-reference> <server-name>
  148. # Remove a catalog
  149. docker mcp catalog remove <oci-reference>
  150. # Tag a catalog
  151. docker mcp catalog tag <source>:<tag> <target>:<tag>
  152. ```
  153. More about [importing from the OSS MCP Community Registry](docs/catalog.md#importing-from-the-oss-mcp-community-registry).
  154. ### MCP Gateway Operations
  155. Start up an MCP Gateway. This can be used for one client, or to service multiple clients if using either `sse` or `streaming` transports.
  156. ```bash
  157. # Run the MCP gateway (stdio, using the default profile)
  158. docker mcp gateway run
  159. # Run with a specific profile
  160. docker mcp gateway run --profile dev-tools
  161. # Run the MCP gateway (streaming)
  162. docker mcp gateway run --port 8080 --transport streaming
  163. ```
  164. If no `--profile` flag is provided, the gateway uses the `default` profile.
  165. * more about [the MCP Gateway](docs/mcp-gateway.md)
  166. ### Client Connection
  167. Connect AI clients to the MCP gateway.
  168. ```bash
  169. # List client configurations
  170. docker mcp client ls
  171. # Connect a client to a profile
  172. docker mcp client connect <client-name> --profile <profile-id>
  173. # Disconnect from a client
  174. docker mcp client disconnect <client-name>
  175. ```
  176. ### Secrets and OAuth
  177. Configure MCP servers that require either secrets or OAuth.
  178. ```bash
  179. # Manage secrets
  180. docker mcp secret --help
  181. # Handle OAuth flows
  182. docker mcp oauth --help
  183. # export any desktop secrets needed by either server1 or server2
  184. # (temporary requirement to export secrets for docker cloud runs - this command
  185. # will no longer be required once Docker Cloud can access secret stores)
  186. docker mcp secret export server1 server2
  187. ```
  188. ### Tool Management
  189. ```bash
  190. # Count available tools
  191. docker mcp tools count
  192. # List all available MCP tools
  193. docker mcp tools ls
  194. # List all available MCP tools in JSON format
  195. docker mcp tools ls --format=json
  196. # Inspect a specific tool
  197. docker mcp tools inspect <tool-name>
  198. # Call a tool with arguments
  199. docker mcp tools call <tool-name> [arguments...]
  200. # Enable/disable tools for a server in a profile
  201. docker mcp profile tools <profile-id> --enable <server>.<tool>
  202. docker mcp profile tools <profile-id> --disable <server>.<tool>
  203. ```
  204. ## Configuration
  205. Configuration is stored in a local database. Profiles, catalogs, and server configuration are managed through the `docker mcp profile` and `docker mcp catalog` commands. Feature flags are stored in `~/.docker/config.json`.
  206. ### Environment Variables
  207. The MCP CLI respects the following environment variables for client configuration:
  208. - **`CLAUDE_CONFIG_DIR`**: Override the default Claude Code configuration directory (`~/.claude`). When set, Claude Code will use `$CLAUDE_CONFIG_DIR/.claude.json` instead of `~/.claude.json` for its MCP server configuration. This is useful for:
  209. - Maintaining separate Claude Code installations for work and personal use
  210. - Testing configuration changes in isolation
  211. - Managing multiple Claude Code profiles
  212. Example usage:
  213. ```bash
  214. # Set custom Claude Code configuration directory
  215. export CLAUDE_CONFIG_DIR=/path/to/custom/config
  216. # Connect MCP Gateway to Claude Code
  217. docker mcp client connect claude-code --profile dev-tools --global
  218. # Claude Code will now use /path/to/custom/config/.claude.json
  219. ```
  220. ## Architecture
  221. The Docker MCP CLI implements a gateway pattern:
  222. ```
  223. AI Client → MCP Gateway → MCP Servers (Docker Containers)
  224. ```
  225. - **AI Client**: Language model or AI application
  226. - **MCP Gateway**: This CLI tool managing protocol translation and routing
  227. - **MCP Servers**: Individual MCP servers running in Docker containers
  228. See [docs/message-flow.md](docs/message-flow.md) for detailed message flow diagrams.
  229. ## Contributing
  230. The build instructions are available in the [contribution guide](CONTRIBUTING.md).
  231. ## License
  232. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  233. ## Support
  234. - 💬 [Troubleshooting](/docs/troubleshooting.md)
  235. - 📖 [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25)
  236. - 🐳 [Docker Desktop Documentation](https://docs.docker.com/desktop/)
  237. - 🐛 [Report Issues](https://github.com/docker/mcp-gateway/issues)
  238. - 💬 [Discussions](https://github.com/docker/mcp-gateway/discussions)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.