Docker MCP Toolkit Setup Guide

0. Prerequisites

Docker Desktop: Installed and running.
Gemini CLI: Installed and functional.
UniFi Credentials: Controller IP, Admin Username, and Password.

1. The Setup Process

Step 1: Securely Store Credentials

Use the Docker MCP secret manager to store your UniFi credentials in your OS's secure Keychain. Replace the placeholder values with your actual info.

docker mcp secret set UNIFI_NETWORK_HOST="192.168.1.1"
docker mcp secret set UNIFI_NETWORK_USERNAME="admin"
docker mcp secret set UNIFI_NETWORK_PASSWORD="your-password"
docker mcp secret set UNIFI_NETWORK_VERIFY_SSL="false"

Step 2: Create the Custom Catalog

Create a unifi-catalog.yaml file. This tells the toolkit where the image lives and maps your Keychain secrets to the container's environment variables.

cat <<EOF > unifi-catalog.yaml
version: 2
name: unifi-homelab
displayName: UniFi Homelab Servers
registry:
  unifi-network:
    title: "UniFi Network Server"
    description: "MCP Server for Ubiquiti UniFi Network"
    image: "ghcr.io/sirkirby/unifi-network-mcp:latest"
    secrets:
      - name: UNIFI_NETWORK_HOST
        env: UNIFI_NETWORK_HOST
      - name: UNIFI_NETWORK_USERNAME
        env: UNIFI_NETWORK_USERNAME
      - name: UNIFI_NETWORK_PASSWORD
        env: UNIFI_NETWORK_PASSWORD
      - name: UNIFI_NETWORK_VERIFY_SSL
        env: UNIFI_NETWORK_VERIFY_SSL
EOF

Step 3: Import Catalog & Add Server

Import the YAML file into the Docker MCP internal database, then add the server to make it available to the Gateway.

docker mcp catalog import ./unifi-catalog.yaml
docker mcp server add unifi-network
docker mcp server ls  # Optional: Verify it was added successfully

Step 4: Configure Gemini CLI

Update your Gemini CLI settings file (typically ~/.gemini/settings.json) to point to the global Docker MCP gateway.

{
  "mcpServers": {
    "docker-mcp-gateway": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

2. Usage & Troubleshooting

Usage

Once configured, restart your Gemini CLI. The Docker Gateway will handle spinning the container up and down automatically. Just ask natural language questions:

💬 "List all connected clients on my Guest VLAN."
💬 "Are there any offline devices on my network?"
💬 "Show me the port status for my main switch."

Troubleshooting (Live Logs)

If the server fails to connect, you can watch the container's output in real-time. Do this while Gemini is "thinking" about your prompt.

Find the running container ID: docker ps
Tail the logs for that specific container: docker logs -f <container-id>
Look for connection timeouts or 401 Unauthorized errors.

3. Generalizing for Other MCP Servers

You can use this exact same framework for almost any Dockerized MCP server (e.g., PostgreSQL, GitHub, File System). You simply modify the Catalog YAML.

To add a new server, follow these steps:

Set the new server's required credentials using docker mcp secret set VAR_NAME="value"
Add a new block under the registry: key in your catalog.yaml file.
Update the image: string to point to the new server's Docker image.
Map the new secrets to the container's expected environment variables.
Run docker mcp catalog import ./catalog.yaml to update the database.
Run docker mcp server add <new-server-name>.