Skip to main content
Glama

Smart Bulb MCP Server

Node.js와 TypeScript로 구축된 Model Context Protocol(MCP) 서버로, IP를 통해 스마트 전구를 제어합니다. 지원 기능:

  • 모의/시뮬레이션 전구: 실제 하드웨어 없이 로컬 테스트 및 개발을 위한 기능입니다.

  • Yeelight/Xiaomi 전구: 표준 TCP 포트 55443(로컬 제어 JSON-RPC 프로토콜)을 사용하여 실제 물리적 스마트 전구를 제어합니다.

기능

  • IP로 연결: 로컬 네트워크의 서로 다른 전구에 동적으로 연결할 수 있습니다.

  • 전원 제어: 전구를 켜거나 끕니다.

  • 밝기 및 불투명도: 전구 밝기/강도를 1%에서 100%로 조절합니다.

  • 색상 제어: RGB 좌표 또는 16진수 색상 코드를 사용하여 색상을 설정합니다.

  • 상태 조회: 전구의 현재 상태를 실시간으로 가져옵니다.


Related MCP server: wiz-light-mcp

시작하기

1. 빌드하기

먼저 의존성을 설치하고 TypeScript 파일을 컴파일합니다:

# Install dependencies
npm install

# Compile the TypeScript files
npm run build

컴파일된 파일은 dist/ 디렉터리에 출력됩니다.

2. 실행 / 개발

표준 I/O(Stdio)를 사용하여 서버를 직접 실행할 수 있습니다:

# Run the built JS
npm start

# Compile and run in development mode
npm run dev

MCP 클라이언트로 구성하기

이 서버를 MCP 클라이언트(예: Claude Desktop 또는 Cursor)와 함께 사용하려면 구성 파일에 서버 설정을 추가하세요.

Claude Desktop 사용 시

claude_desktop_config.json 파일을 편집합니다(Windows에서는 보통 %APPDATA%\Claude, macOS에서는 ~/Library/Application Support/Claude에 있습니다):

{
  "mcpServers": {
    "smart-bulb": {
      "command": "node",
      "args": ["D:/Palwinder/mcp-server-bulb/dist/index.js"]
    }
  }
}

참고: D:/Palwinder/mcp-server-bulb/dist/index.js를 사용자 시스템의 dist/index.js 절대 경로로 변경하세요.


노출되는 MCP 도구

서버가 연결되면 호스트 LLM은 다음의 도구들을 이용할 수 있습니다:

1. connect_bulb

지정된 IP 주소의 전구에 연결합니다.

  • 인자:

    • ip (string, 필수): IP 주소 (예: "192.168.1.15" 또는 "127.0.0.1").

    • type (enum ["mock", "yeelight"], 기본값: "mock"): 드라이버 유형. 실제 하드웨어 없이 서버 기능을 테스트하려면 "mock"을, 실제 Yeelight 전구에는 "yeelight"를 사용합니다.

    • port (number, 선택): 사용할 포트. Yeelight는 기본값 55443, Mock는 9999를 사용합니다.

2. disconnect_bulb

현재 연결된 전구와의 연결을 끊습니다.

  • 인자: 없습니다.

3. get_bulb_state

연결 상태, 전원 상태, 밝기/불투명도 백분율 및 RGB 색상을 조회합니다.

  • 인자: 없습니다.

4. set_bulb_power

전구를 켜거나 끕니다.

  • 인자:

    • power (boolean, 필수): 켜려면 ON true, 끄려면 false.

5. set_bulb_brightness

전구의 밝기/불투명도를 설정합니다.

  • 인자:

    • brightness (number, 필수): 1부터 100까지의 값입니다.

6. set_bulb_color_rgb

RGB 값을 사용하여 전구의 색상을 설정합니다.

  • 인자:

    • r (number, 필수): 빨간색 성분 0 - 255.

    • g (number, 필수): 녹색 성분 0 - 255.

    • b (number, 필수): 파란색 성분 0 - 255.

7. set_bulb_color_hex

hex 색상 코드를 사용하여 전구의 색상을 설정합니다.

  • 인자:

    • hex (string, 필수): Hex 코드 (예: "#FF0000" 또는 "00FF00").


OpenAI 연결 클라이언트

src/openai-client.ts를 사용하여 버퍼에 클라이언트 래퍼를 구현했습니다. 이 래퍼는 프롬프트를 OpenAI에 직접 전달할 수 있게 해주며, OpenAI가 MCP 도구를 자동으로 호출하여 스마트 전구에 대한 작업을 수행합니다.

클라이언트 설정 및 실행하기

  1. OpenAI API 키를 설정하세요: Windows(PowerShell)에서:

    $env:OPENAI_API_KEY="your-actual-api-key"

    macOS/Linux(Bash)에서:

    export OPENAI_API_KEY="your-actual-api-key"
  2. 클라이언트 실행하기:

    • 대화형 CLI 모드:

      npm run client

      셸 프롬프트가 열립니다. 다음을 입력해 보세요:

      "모의 전구에 연결해서 켠 다음, 밝기를 80%로 설정하고 노란색으로 바꿔줘."

    • 일회성 명령 모드: 프롬프트를 인数로 직접 전달하세요:

      npm run client -- "connect to the mock bulb, turn it on, and set color to blue"
  3. 모델 커스커마이즈(선택): 기본적으로 gpt-4o-mini를 사용합니다. OPENAI_MODEL 환경 변수를 설정하면 바꿀 수 있습니다:

    $env:OPENAI_MODEL="gpt-4o"

개발자 세부 내용 & 아키텍처

이 프로젝트는 모듈 구조로 이루어져 있습니다:

  • src/bulb/interface.ts: 공통 계약(ISmartBulb)과 상태 형태(BulbState)를 정의합니다.

  • src/bulb/mock.ts: 메모리 내에서 네트워크 지연과 상태 변경을 모사하는 시레이션 전구 인스턴스입니다.

  • src/bulb/yeelight.ts: 제3자 SDK 의존 없이 물리 Yeelight WiFi 전구과 JSON-RPC 패킷을 직접 주고 받기 위한 수동 TCP 라인 기반 버퍼 파서를 구현합니다.

  • src/index.ts: @modelcontextprotocol/server 도구를 구성하고 마운트하며 연결 상태와 유효성 검사 스키마를 처리합니다.

  • src/openai-client.ts: MCP 서버를 하위 프로세스로 실행하고, 모든 도구를 동적으로 로드하여 OpenAI 함수로 노출하며, 다중 턴 대화형 도구 실행 루프를 처리합니다.


만든 이: Palwinder Singh

Available Tools

7 tools
connect_bulbA

Connect to a smart bulb at a given IP address. Supports both real Yeelight bulbs and mock bulbs for testing.

Inputs: ip (required), port, type.

disconnect_bulbA

Disconnect from the currently active smart bulb.

Inputs: no named parameters.

get_bulb_stateA

Retrieve the current state (power status, brightness/opacity, color) of the connected smart bulb.

Inputs: no named parameters.

set_bulb_brightnessA

Set the brightness (intensity/opacity) of the connected smart bulb.

Inputs: brightness (required).

set_bulb_color_hexA

Set the color of the connected smart bulb using a hexadecimal color code (e.g. '#FF0000' or '00FF00').

Inputs: hex (required).

set_bulb_color_rgbB

Set the color of the connected smart bulb using RGB values (0-255).

Inputs: b (required), g (required), r (required).

set_bulb_powerB

Turn the connected smart bulb on or off.

Inputs: power (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    Tools have distinct purposes: connect, disconnect, state retrieval, and setting power, brightness, and color. The only overlap is between set_bulb_color_rgb and set_bulb_color_hex, which serve the same function with different input formats, but their descriptions clearly differentiate them, causing minimal confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., connect_bulb, get_bulb_state, set_bulb_power). The naming style is uniform with snake_case and clear action-target structure, making the API predictable and easy to navigate.

    Tool Count5/5

    With 7 tools, the set is well-scoped for a smart bulb control server. Each tool addresses a core operation (connection, state, power, brightness, color) without redundant or excessive entries, fitting comfortably within the ideal 3-15 range.

    Completeness4/5

    The server covers essential smart bulb operations: connection management, state retrieval, power, brightness, and color control. A minor gap is the lack of color temperature or scene settings, which are common on smart bulbs, but the core workflows are fully supported and no critical dead ends exist.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for controlling WiZ smart lights locally via UDP: discover bulbs, power control, color, temperature, and scenes.
      10
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables local network control of Tuya and Smart Life smart home devices without cloud round-trips, including power, brightness, color, and raw datapoint operations.
      9
      MIT