Docker MCP Server

Instructions

Implementation Reference

• src/index.ts:258-310 (handler)

  The main handler function that constructs and executes the 'docker run' command using child_process.execAsync based on the provided arguments, returning the stdout as text content.

  private async runContainer(args: RunContainerArgs) {
    if (!args.image) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Image parameter is required'
      );
    }
  
    let command = 'docker run';
    
    if (args.detach) {
      command += ' -d';
    }
    
    if (args.name) {
      command += ` --name ${args.name}`;
    }
    
    if (args.ports && Array.isArray(args.ports)) {
      args.ports.forEach((port: string) => {
        command += ` -p ${port}`;
      });
    }
    
    if (args.volumes && Array.isArray(args.volumes)) {
      args.volumes.forEach((volume: string) => {
        command += ` -v ${volume}`;
      });
    }
    
    if (args.env && Array.isArray(args.env)) {
      args.env.forEach((env: string) => {
        command += ` -e ${env}`;
      });
    }
    
    command += ` ${args.image}`;
    
    if (args.command) {
      command += ` ${args.command}`;
    }
    
    const { stdout } = await execAsync(command);
    
    return {
      content: [
        {
          type: 'text',
          text: stdout.trim(),
        },
      ],
    };
  }

• src/index.ts:21-29 (schema)

  TypeScript interface defining the structure of input arguments for the run_container tool.

  interface RunContainerArgs {
    image: string;
    name?: string;
    detach?: boolean;
    ports?: string[];
    volumes?: string[];
    env?: string[];
    command?: string;
  }

• src/index.ts:93-135 (schema)

  JSON schema for input validation in the tool's registration.

  inputSchema: {
    type: 'object',
    properties: {
      image: {
        type: 'string',
        description: 'Docker image to run',
      },
      name: {
        type: 'string',
        description: 'Name for the container',
      },
      detach: {
        type: 'boolean',
        description: 'Run container in background',
      },
      ports: {
        type: 'array',
        items: {
          type: 'string',
        },
        description: 'Port mappings (e.g. ["8080:80"])',
      },
      volumes: {
        type: 'array',
        items: {
          type: 'string',
        },
        description: 'Volume mappings (e.g. ["/host/path:/container/path"])',
      },
      env: {
        type: 'array',
        items: {
          type: 'string',
        },
        description: 'Environment variables (e.g. ["KEY=value"])',
      },
      command: {
        type: 'string',
        description: 'Command to run in the container',
      },
    },
    required: ['image'],
  },

• src/index.ts:90-136 (registration)

  Registration of the 'run_container' tool in the ListTools response, including name, description, and schema.

  {
    name: 'run_container',
    description: 'Run a Docker container',
    inputSchema: {
      type: 'object',
      properties: {
        image: {
          type: 'string',
          description: 'Docker image to run',
        },
        name: {
          type: 'string',
          description: 'Name for the container',
        },
        detach: {
          type: 'boolean',
          description: 'Run container in background',
        },
        ports: {
          type: 'array',
          items: {
            type: 'string',
          },
          description: 'Port mappings (e.g. ["8080:80"])',
        },
        volumes: {
          type: 'array',
          items: {
            type: 'string',
          },
          description: 'Volume mappings (e.g. ["/host/path:/container/path"])',
        },
        env: {
          type: 'array',
          items: {
            type: 'string',
          },
          description: 'Environment variables (e.g. ["KEY=value"])',
        },
        command: {
          type: 'string',
          description: 'Command to run in the container',
        },
      },
      required: ['image'],
    },
  },

• src/index.ts:193-194 (handler)

  Dispatcher in CallToolRequest handler that routes to the runContainer method.

  case 'run_container':
    return await this.runContainer(request.params.arguments as unknown as RunContainerArgs);