Windows System MCP

Instructions

Implementation Reference

• src/tools/service.ts:46-86 (handler)

  Main handler function for the service_manager tool. Dispatches to specific service management actions based on the 'action' parameter.

  async run(args: {
    action: string;
    service_name?: string;
    status_filter?: string;
    startup_type_filter?: string;
    search_term?: string;
    limit?: number;
  }) {
    try {
      switch (args.action) {
        case "list_services":
          return await this.listServices(args.status_filter, args.startup_type_filter, args.limit);
        case "get_service_details":
          return await this.getServiceDetails(args.service_name!);
        case "start_service":
          return await this.startService(args.service_name!);
        case "stop_service":
          return await this.stopService(args.service_name!);
        case "restart_service":
          return await this.restartService(args.service_name!);
        case "get_service_status":
          return await this.getServiceStatus(args.service_name!);
        case "find_service":
          return await this.findService(args.search_term!);
        case "get_running_services":
          return await this.getRunningServices(args.limit);
        case "get_startup_services":
          return await this.getStartupServices(args.limit);
        default:
          throw new Error(`Unknown action: ${args.action}`);
      }
    } catch (error: any) {
      return {
        content: [{
          type: "text",
          text: `❌ Service management operation failed: ${error.message}`
        }],
        isError: true
      };
    }
  },

• src/tools/service.ts:7-44 (schema)

  Input schema definition for the service_manager tool, including parameters for various actions.

  name: "service_manager",
  description: "Windows service management including listing services, getting service details, starting/stopping services, and monitoring service status",
  parameters: {
    type: "object",
    properties: {
      action: {
        type: "string",
        enum: ["list_services", "get_service_details", "start_service", "stop_service", "restart_service", "get_service_status", "find_service", "get_running_services", "get_startup_services"],
        description: "The service management action to perform"
      },
      service_name: {
        type: "string",
        description: "Service name for specific service operations"
      },
      status_filter: {
        type: "string",
        enum: ["running", "stopped", "paused", "all"],
        description: "Filter services by status (default: all)",
        default: "all"
      },
      startup_type_filter: {
        type: "string",
        enum: ["automatic", "manual", "disabled", "all"],
        description: "Filter services by startup type (default: all)",
        default: "all"
      },
      search_term: {
        type: "string",
        description: "Search term for finding services"
      },
      limit: {
        type: "number",
        description: "Limit number of results (default: 50)",
        default: 50
      }
    },
    required: ["action"]
  },

• src/index.ts:47-51 (registration)

  Registration of service_manager tool in the MCP server's list tools handler.

  {
    name: serviceManagerTool.name,
    description: serviceManagerTool.description,
    inputSchema: serviceManagerTool.parameters
  },

• src/index.ts:79-80 (registration)

  Dispatcher registration for handling calls to the service_manager tool in the MCP server's call tool handler.

  case "service_manager":
    return await serviceManagerTool.run(args as any);

• src/tools/service.ts:88-118 (helper)

  Helper method to list Windows services with optional status, startup type filters, and limit.

  async listServices(statusFilter = "all", startupTypeFilter = "all", limit = 50) {
    try {
      let whereClause = "";
      const conditions: string[] = [];
      
      if (statusFilter !== "all") {
        conditions.push(`$_.Status -eq '${this.mapStatusFilter(statusFilter)}'`);
      }
      
      if (startupTypeFilter !== "all") {
        conditions.push(`$_.StartType -eq '${this.mapStartupTypeFilter(startupTypeFilter)}'`);
      }
      
      if (conditions.length > 0) {
        whereClause = `| Where-Object {${conditions.join(' -and ')}}`;
      }
      
      const command = `Get-Service ${whereClause} | Select-Object -First ${limit} Name, DisplayName, Status, StartType | Sort-Object DisplayName | Format-Table -AutoSize`;
      
      const { stdout } = await execAsync(`powershell -Command "${command}"`);
      
      return {
        content: [{
          type: "text",
          text: `# Windows Services\n\nStatus Filter: ${statusFilter}\nStartup Type Filter: ${startupTypeFilter}\nLimit: ${limit}\n\n\`\`\`\n${stdout}\n\`\`\``
        }]
      };
    } catch (error: any) {
      throw new Error(`Failed to list services: ${error.message}`);
    }
  },