OpenHue MCP Server

Instructions

Implementation Reference

• src/index.ts:248-269 (handler)

  Handler for the 'control-light' tool. Parses input arguments using LightActionSchema, constructs an OpenHue CLI command to control the specified light (on/off, brightness, color, temperature), executes it via Docker, and returns a success message.

  case "control-light": {
    const params = LightActionSchema.parse(args);
    let command = `set light "${params.target}" --${params.action}`;
    if (params.brightness !== undefined) {
      command += ` --brightness ${params.brightness}`;
    }
    if (params.color) {
      command += ` --color ${params.color}`;
    }
    if (params.temperature) {
      command += ` --temperature ${params.temperature}`;
    }
    await executeHueCommand(command);
    return {
      content: [
        {
          type: "text",
          text: `Successfully set light "${params.target}" to ${params.action}`,
        },
      ],
    };
  }

• src/index.ts:28-34 (schema)

  Zod schema used to validate and parse the input parameters for the 'control-light' tool in the handler.

  const LightActionSchema = z.object({
    target: z.string(),
    action: z.enum(["on", "off"]),
    brightness: z.number().min(0).max(100).optional(),
    color: z.string().optional(),
    temperature: z.number().min(153).max(500).optional(),
  });

• src/index.ts:99-133 (registration)

  Registration of the 'control-light' tool in the list returned by ListToolsRequestSchema, including name, description, and input schema definition.

  {
    name: "control-light",
    description: "Control a specific Hue light",
    inputSchema: {
      type: "object",
      properties: {
        target: {
          type: "string",
          description: "Light ID or name",
        },
        action: {
          type: "string",
          enum: ["on", "off"],
          description: "Turn light on or off",
        },
        brightness: {
          type: "number",
          minimum: 0,
          maximum: 100,
          description: "Optional brightness level (0-100)",
        },
        color: {
          type: "string",
          description: "Optional color name (e.g., 'red', 'blue')",
        },
        temperature: {
          type: "number",
          minimum: 153,
          maximum: 500,
          description: "Optional color temperature in Mirek",
        },
      },
      required: ["target", "action"],
    },
  },

• src/index.ts:64-76 (helper)

  Helper function that executes OpenHue CLI commands via Docker, used by the control-light handler to perform the actual light control.

  async function executeHueCommand(command: string): Promise<string> {
    try {
      const { stdout, stderr } = await execAsync(buildDockerCommand(command));
      if (stderr) {
        console.error("Command error:", stderr);
        throw new Error(stderr);
      }
      return stdout;
    } catch (error) {
      console.error("Execution error:", error);
      throw error;
    }
  }