Docker MCP Server

Instructions

Implementation Reference

• src/index.ts:738-818 (handler)

  The main handler function for the 'docker_remote_connection' tool. It processes actions like 'connect', 'disconnect', 'status', and 'test' by interacting with the RemoteDockerManager class.

  async ({ action, host, user, keyPath }) => {
    try {
      switch (action) {
        case "connect":
          if (!host) {
            throw new Error("Host is required for connection");
          }
          
          // Configure SSH connection if needed
          if (host.startsWith("ssh://")) {
            const sshHost = host.replace("ssh://", "");
            if (user && !sshHost.includes("@")) {
              host = `ssh://${user}@${sshHost}`;
            }
          }
          
          RemoteDockerManager.setDockerHost(host);
          const isConnected = await RemoteDockerManager.testConnection();
          
          if (!isConnected) {
            throw new Error("Failed to connect to remote Docker host");
          }
          
          return {
            content: [
              {
                type: "text",
                text: `✅ Successfully connected to Docker host: ${host}\n\nUse 'docker_remote_connection' with action 'status' to check connection status.`
              }
            ]
          };
  
        case "disconnect":
          RemoteDockerManager.setDockerHost("");
          delete process.env.DOCKER_HOST;
          
          return {
            content: [
              {
                type: "text",
                text: "✅ Disconnected from remote Docker host. Using local Docker daemon."
              }
            ]
          };
  
        case "status":
          const connectionInfo = await RemoteDockerManager.getConnectionInfo();
          return {
            content: [
              {
                type: "text",
                text: `## Docker Connection Status\n\n${connectionInfo}`
              }
            ]
          };
  
        case "test":
          const testResult = await RemoteDockerManager.testConnection();
          const currentHost = RemoteDockerManager.getDockerHost();
          
          return {
            content: [
              {
                type: "text",
                text: `## Connection Test\n\nHost: ${currentHost || 'local'}\nStatus: ${testResult ? '✅ Connected' : '❌ Failed'}`
              }
            ]
          };
      }
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error with remote connection: ${error instanceof Error ? error.message : String(error)}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:728-737 (schema)

  The schema definition for the 'docker_remote_connection' tool, including title, description, and Zod inputSchema for validation.

  {
    title: "Remote Docker Connection",
    description: "Connect to remote Docker hosts via SSH or configure Docker host",
    inputSchema: {
      action: z.enum(["connect", "disconnect", "status", "test"]).describe("Connection action"),
      host: z.string().optional().describe("Docker host URL (e.g., ssh://user@host, tcp://host:2376)"),
      user: z.string().optional().describe("SSH username"),
      keyPath: z.string().optional().describe("Path to SSH private key")
    }
  },

• src/index.ts:726-819 (registration)

  The server.registerTool call that registers the 'docker_remote_connection' tool with its schema and handler function.

  server.registerTool(
    "docker_remote_connection",
    {
      title: "Remote Docker Connection",
      description: "Connect to remote Docker hosts via SSH or configure Docker host",
      inputSchema: {
        action: z.enum(["connect", "disconnect", "status", "test"]).describe("Connection action"),
        host: z.string().optional().describe("Docker host URL (e.g., ssh://user@host, tcp://host:2376)"),
        user: z.string().optional().describe("SSH username"),
        keyPath: z.string().optional().describe("Path to SSH private key")
      }
    },
    async ({ action, host, user, keyPath }) => {
      try {
        switch (action) {
          case "connect":
            if (!host) {
              throw new Error("Host is required for connection");
            }
            
            // Configure SSH connection if needed
            if (host.startsWith("ssh://")) {
              const sshHost = host.replace("ssh://", "");
              if (user && !sshHost.includes("@")) {
                host = `ssh://${user}@${sshHost}`;
              }
            }
            
            RemoteDockerManager.setDockerHost(host);
            const isConnected = await RemoteDockerManager.testConnection();
            
            if (!isConnected) {
              throw new Error("Failed to connect to remote Docker host");
            }
            
            return {
              content: [
                {
                  type: "text",
                  text: `✅ Successfully connected to Docker host: ${host}\n\nUse 'docker_remote_connection' with action 'status' to check connection status.`
                }
              ]
            };
  
          case "disconnect":
            RemoteDockerManager.setDockerHost("");
            delete process.env.DOCKER_HOST;
            
            return {
              content: [
                {
                  type: "text",
                  text: "✅ Disconnected from remote Docker host. Using local Docker daemon."
                }
              ]
            };
  
          case "status":
            const connectionInfo = await RemoteDockerManager.getConnectionInfo();
            return {
              content: [
                {
                  type: "text",
                  text: `## Docker Connection Status\n\n${connectionInfo}`
                }
              ]
            };
  
          case "test":
            const testResult = await RemoteDockerManager.testConnection();
            const currentHost = RemoteDockerManager.getDockerHost();
            
            return {
              content: [
                {
                  type: "text",
                  text: `## Connection Test\n\nHost: ${currentHost || 'local'}\nStatus: ${testResult ? '✅ Connected' : '❌ Failed'}`
                }
              ]
            };
        }
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error with remote connection: ${error instanceof Error ? error.message : String(error)}`
            }
          ],
          isError: true
        };
      }
    }
  );

• src/index.ts:321-348 (helper)

  The RemoteDockerManager class providing static methods for managing Docker host connections, testing connectivity, and getting connection info, used by the tool handler.

  class RemoteDockerManager {
    private static currentHost: string | null = null;
  
    static setDockerHost(host: string): void {
      this.currentHost = host;
      process.env.DOCKER_HOST = host;
    }
  
    static getDockerHost(): string | null {
      return this.currentHost || process.env.DOCKER_HOST || null;
    }
  
    static async testConnection(): Promise<boolean> {
      try {
        await executeDockerCommand("docker version");
        return true;
      } catch {
        return false;
      }
    }
  
    static async getConnectionInfo(): Promise<string> {
      const host = this.getDockerHost();
      const isConnected = await this.testConnection();
      
      return `Docker Host: ${host || 'local'}\nConnection: ${isConnected ? '✅ Connected' : '❌ Failed'}`;
    }
  }