create_container

Create and run Docker containers with configurable options for ports, volumes, environment variables, networks, and resource management.

Instructions

Create and run Docker containers with advanced options

Input Schema

TableJSON Schema

Name	Required	Description
`image`	Yes	Docker image to run
`name`	No	Container name
`ports`	No	Port mappings (e.g., ['8080:80', '3000:3000'])
`volumes`	No	Volume mounts (e.g., ['/host/path:/container/path'])
`environment`	No	Environment variables
`network`	No	Network to connect to
`detached`	No	Run in detached mode
`interactive`	No	Run in interactive mode
`command`	No	Command to run in container
`workdir`	No	Working directory
`restart`	No	Restart policy
`healthCheck`	No	Health check configuration
`resources`	No	Resource constraints
`security`	No	Security options
`labels`	No	Container labels
`hostname`	No	Container hostname
`domainname`	No	Container domain name
`projectName`	No	Project name for resource grouping

Implementation Reference

src/index.ts:1545-1655 (handler)

The handler function for the create_container tool. It constructs a docker run command based on the provided parameters (image, ports, volumes, env, etc.) including advanced options like health checks, resources, security, and executes it using executeDockerCommand.

async ({ image, name, ports, volumes, environment, network, detached, interactive, command, workdir, restart, healthCheck, resources, security, labels, hostname, domainname, projectName }) => {
  try {
    let dockerCommand = "docker run";
    
    // Add flags
    if (detached && !interactive) dockerCommand += " -d";
    if (interactive) dockerCommand += " -it";
    if (name) dockerCommand += ` --name ${name}`;
    
    // Add port mappings
    if (ports && ports.length > 0) {
      ports.forEach(port => {
        dockerCommand += ` -p ${port}`;
      });
    }
    
    // Add volume mounts
    if (volumes && volumes.length > 0) {
      volumes.forEach(volume => {
        dockerCommand += ` -v ${volume}`;
      });
    }
    
    // Add environment variables
    if (environment) {
      Object.entries(environment).forEach(([key, value]) => {
        dockerCommand += ` -e ${key}=${value}`;
      });
    }
    
    // Add network
    if (network) dockerCommand += ` --network ${network}`;
    
    // Add working directory
    if (workdir) dockerCommand += ` -w ${workdir}`;
    
    // Add restart policy
    if (restart) dockerCommand += ` --restart ${restart}`;
    
    // Add hostname
    if (hostname) dockerCommand += ` --hostname ${hostname}`;
    
    // Add domain name
    if (domainname) dockerCommand += ` --domainname ${domainname}`;
    
    // Add health check
    if (healthCheck) {
      dockerCommand += ` --health-cmd "${healthCheck.test}"`;
      if (healthCheck.interval) dockerCommand += ` --health-interval ${healthCheck.interval}`;
      if (healthCheck.timeout) dockerCommand += ` --health-timeout ${healthCheck.timeout}`;
      if (healthCheck.retries) dockerCommand += ` --health-retries ${healthCheck.retries}`;
    }
    
    // Add resource constraints
    if (resources) {
      if (resources.memory) dockerCommand += ` --memory ${resources.memory}`;
      if (resources.cpus) dockerCommand += ` --cpus ${resources.cpus}`;
      if (resources.memorySwap) dockerCommand += ` --memory-swap ${resources.memorySwap}`;
    }
    
    // Add security options
    if (security) {
      if (security.user) dockerCommand += ` --user ${security.user}`;
      if (security.readOnly) dockerCommand += " --read-only";
      if (security.tmpfs) {
        security.tmpfs.forEach(tmpfs => {
          dockerCommand += ` --tmpfs ${tmpfs}`;
        });
      }
    }
    
    // Add labels
    if (labels) {
      Object.entries(labels).forEach(([key, value]) => {
        dockerCommand += ` --label "${key}=${value}"`;
      });
    }
    
    // Add image
    dockerCommand += ` ${image}`;
    
    // Add command
    if (command) dockerCommand += ` ${command}`;
    
    // Add project label if specified
    if (projectName) {
      dockerCommand = ProjectManager.addProjectLabel(dockerCommand, projectName);
    }
    
    const result = await executeDockerCommand(dockerCommand);
    
    return {
      content: [
        {
          type: "text",
          text: `Container created successfully:\n\nCommand: ${dockerCommand}\n\nOutput:\n${result.stdout}${result.stderr ? `\nWarnings:\n${result.stderr}` : ""}`
        }
      ]
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Error creating container: ${error instanceof Error ? error.message : String(error)}`
        }
      ],
      isError: true
    };
  }
}

src/index.ts:1507-1543 (schema)

The input schema definition for the create_container tool, using Zod for validation of parameters like image, ports, volumes, environment variables, advanced options such as healthCheck, resources, security, etc.

{
  title: "Create and Run Docker Containers",
  description: "Create and run Docker containers with advanced options",
  inputSchema: {
    image: z.string().describe("Docker image to run"),
    name: z.string().optional().describe("Container name"),
    ports: z.array(z.string()).optional().describe("Port mappings (e.g., ['8080:80', '3000:3000'])"),
    volumes: z.array(z.string()).optional().describe("Volume mounts (e.g., ['/host/path:/container/path'])"),
    environment: z.record(z.string()).optional().describe("Environment variables"),
    network: z.string().optional().describe("Network to connect to"),
    detached: z.boolean().optional().default(true).describe("Run in detached mode"),
    interactive: z.boolean().optional().default(false).describe("Run in interactive mode"),
    command: z.string().optional().describe("Command to run in container"),
    workdir: z.string().optional().describe("Working directory"),
    restart: z.enum(["no", "on-failure", "always", "unless-stopped"]).optional().describe("Restart policy"),
    // Advanced options
    healthCheck: z.object({
      test: z.string(),
      interval: z.string().optional(),
      timeout: z.string().optional(),
      retries: z.number().optional()
    }).optional().describe("Health check configuration"),
    resources: z.object({
      memory: z.string().optional(),
      cpus: z.string().optional(),
      memorySwap: z.string().optional()
    }).optional().describe("Resource constraints"),
    security: z.object({
      user: z.string().optional(),
      readOnly: z.boolean().optional(),
      tmpfs: z.array(z.string()).optional()
    }).optional().describe("Security options"),
    labels: z.record(z.string()).optional().describe("Container labels"),
    hostname: z.string().optional().describe("Container hostname"),
    domainname: z.string().optional().describe("Container domain name"),
    projectName: z.string().optional().describe("Project name for resource grouping")
  }

src/index.ts:1504-1656 (registration)

The registration of the create_container tool on the MCP server, including the tool name, schema, and handler function.

// Register Docker container creation and management tool
server.registerTool(
  "create_container",
  {
    title: "Create and Run Docker Containers",
    description: "Create and run Docker containers with advanced options",
    inputSchema: {
      image: z.string().describe("Docker image to run"),
      name: z.string().optional().describe("Container name"),
      ports: z.array(z.string()).optional().describe("Port mappings (e.g., ['8080:80', '3000:3000'])"),
      volumes: z.array(z.string()).optional().describe("Volume mounts (e.g., ['/host/path:/container/path'])"),
      environment: z.record(z.string()).optional().describe("Environment variables"),
      network: z.string().optional().describe("Network to connect to"),
      detached: z.boolean().optional().default(true).describe("Run in detached mode"),
      interactive: z.boolean().optional().default(false).describe("Run in interactive mode"),
      command: z.string().optional().describe("Command to run in container"),
      workdir: z.string().optional().describe("Working directory"),
      restart: z.enum(["no", "on-failure", "always", "unless-stopped"]).optional().describe("Restart policy"),
      // Advanced options
      healthCheck: z.object({
        test: z.string(),
        interval: z.string().optional(),
        timeout: z.string().optional(),
        retries: z.number().optional()
      }).optional().describe("Health check configuration"),
      resources: z.object({
        memory: z.string().optional(),
        cpus: z.string().optional(),
        memorySwap: z.string().optional()
      }).optional().describe("Resource constraints"),
      security: z.object({
        user: z.string().optional(),
        readOnly: z.boolean().optional(),
        tmpfs: z.array(z.string()).optional()
      }).optional().describe("Security options"),
      labels: z.record(z.string()).optional().describe("Container labels"),
      hostname: z.string().optional().describe("Container hostname"),
      domainname: z.string().optional().describe("Container domain name"),
      projectName: z.string().optional().describe("Project name for resource grouping")
    }
  },
  async ({ image, name, ports, volumes, environment, network, detached, interactive, command, workdir, restart, healthCheck, resources, security, labels, hostname, domainname, projectName }) => {
    try {
      let dockerCommand = "docker run";
      
      // Add flags
      if (detached && !interactive) dockerCommand += " -d";
      if (interactive) dockerCommand += " -it";
      if (name) dockerCommand += ` --name ${name}`;
      
      // Add port mappings
      if (ports && ports.length > 0) {
        ports.forEach(port => {
          dockerCommand += ` -p ${port}`;
        });
      }
      
      // Add volume mounts
      if (volumes && volumes.length > 0) {
        volumes.forEach(volume => {
          dockerCommand += ` -v ${volume}`;
        });
      }
      
      // Add environment variables
      if (environment) {
        Object.entries(environment).forEach(([key, value]) => {
          dockerCommand += ` -e ${key}=${value}`;
        });
      }
      
      // Add network
      if (network) dockerCommand += ` --network ${network}`;
      
      // Add working directory
      if (workdir) dockerCommand += ` -w ${workdir}`;
      
      // Add restart policy
      if (restart) dockerCommand += ` --restart ${restart}`;
      
      // Add hostname
      if (hostname) dockerCommand += ` --hostname ${hostname}`;
      
      // Add domain name
      if (domainname) dockerCommand += ` --domainname ${domainname}`;
      
      // Add health check
      if (healthCheck) {
        dockerCommand += ` --health-cmd "${healthCheck.test}"`;
        if (healthCheck.interval) dockerCommand += ` --health-interval ${healthCheck.interval}`;
        if (healthCheck.timeout) dockerCommand += ` --health-timeout ${healthCheck.timeout}`;
        if (healthCheck.retries) dockerCommand += ` --health-retries ${healthCheck.retries}`;
      }
      
      // Add resource constraints
      if (resources) {
        if (resources.memory) dockerCommand += ` --memory ${resources.memory}`;
        if (resources.cpus) dockerCommand += ` --cpus ${resources.cpus}`;
        if (resources.memorySwap) dockerCommand += ` --memory-swap ${resources.memorySwap}`;
      }
      
      // Add security options
      if (security) {
        if (security.user) dockerCommand += ` --user ${security.user}`;
        if (security.readOnly) dockerCommand += " --read-only";
        if (security.tmpfs) {
          security.tmpfs.forEach(tmpfs => {
            dockerCommand += ` --tmpfs ${tmpfs}`;
          });
        }
      }
      
      // Add labels
      if (labels) {
        Object.entries(labels).forEach(([key, value]) => {
          dockerCommand += ` --label "${key}=${value}"`;
        });
      }
      
      // Add image
      dockerCommand += ` ${image}`;
      
      // Add command
      if (command) dockerCommand += ` ${command}`;
      
      // Add project label if specified
      if (projectName) {
        dockerCommand = ProjectManager.addProjectLabel(dockerCommand, projectName);
      }
      
      const result = await executeDockerCommand(dockerCommand);
      
      return {
        content: [
          {
            type: "text",
            text: `Container created successfully:\n\nCommand: ${dockerCommand}\n\nOutput:\n${result.stdout}${result.stderr ? `\nWarnings:\n${result.stderr}` : ""}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error creating container: ${error instanceof Error ? error.message : String(error)}`
          }
        ],
        isError: true
      };
    }
  }
);

Docker MCP Server