LIFX API MCP Server

LIFX API MCP Server

LIFX API MCP Server は、LLM を通じて自然言語で LIFX デバイスを操作できる、ローカルの Model Context Protocol（MCP）サーバーです。LIFX HTTP API を使用して、ライトの一覧表示、状態の設定、シーンの有効化、エフェクトの実行などを行えます。コンテキストに応じたリソースと便利なプロンプトも含まれています。

目次

• クイックスタート
• 機能
• インストール
• 設定
• クライアントのセットアップ
• データ保護
• チュートリアル
• Dockerfile
• 免責事項
• サポート

クイックスタート

1. LIFX API トークンを取得します：
   • LIFX Cloud の設定ページにアクセスします。
   • 新しい個人用アクセストークンを生成します。このトークンは安全に保管してください！
2. LIFX MCP Server をインストールします：（方法を1つ選択してください）
   • NPX（推奨）：

     npx -y lifx-api-mcp-server@latest
     

   • Docker：

     docker run --rm -i --network=host --pull=always furey/lifx-api-mcp-server
     

3. API トークンを設定します：
   • 重要な手順： 次のいずれかの方法でトークンを設定します（優先順位順）：
     1. 設定ファイル（推奨）： ~/.lifx-api-mcp-server.jsonc を編集し（npx -y lifx-api-mcp-server@latest config:create で生成）、apiToken フィールドにトークンを追加します。
     2. 環境変数： CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN を設定します。
     3. コマンドライン引数（非推奨）： サーバーの実行時にトークンを渡します（例：npx ... YOUR_TOKEN）。
4. MCP クライアントをセットアップします：
   • 設定ファイルまたは環境変数を使用する場合は、トークン引数を付けずにサーバーを起動するようクライアント（例：Claude Desktop、MCP Inspector）を設定します。
5. ライトを操作します：
   • 自然言語で LIFX デバイスの操作を開始します（チュートリアルを参照）。@lix-api:lifx://lights などのリソースや、@lix-api:effect-creator などのプロンプトを使用します。

機能

ツール

• list-lights：アカウントに属するライトを取得します。セレクターで絞り込めます。
• set-state：選択したライトの状態（電源、色、明るさなど）を設定します。
• set-states：1つのリクエストで、複数のセレクターに対して複数の状態を設定します。
• state-delta：状態のプロパティ（明るさ、色相、彩度、ケルビン、赤外線）を相対量で変更します。
• toggle-power：選択したライトの電源状態を切り替えます。
• breathe-effect：ブリーズ（フェード）エフェクトを実行します。
• pulse-effect：パルス（点滅）エフェクトを実行します。
• move-effect：リニアデバイス（LIFX Z ストリップ）でムーブエフェクトを実行します。
• morph-effect：Tile デバイスでモーフエフェクトを実行します。
• flame-effect：Tile デバイスでフレイムエフェクトを実行します。
• clouds-effect：Tile デバイスでクラウドエフェクトを実行します（FW >= 4.8）。
• sunrise-effect：Tile デバイスでサンライズエフェクトを実行します（FW >= 4.8）。
• sunset-effect：Tile デバイスでサンセットエフェクトを実行します（FW >= 4.8）。
• effects-off：実行中のエフェクトをすべて停止します。
• list-scenes：アカウントで利用可能なシーンを一覧表示します。
• activate-scene：UUID で指定したシーンを有効化します。
• cycle：選択したライトを、あらかじめ定義された状態のリストに沿って切り替えます。
• validate-color：色の文字列を検証し、その構成要素を返します。
• clean：LIFX Clean デバイスを操作します。

リソース

• lifx://lights：利用可能なライトの概要一覧（ID、ラベル、電源状態、接続状態）を提供します。ライブデータを取得します。
• lifx://light/{selector}/state：セレクターに一致するライトの詳細な現在の状態を提供します。セレクターの自動補完に対応しています。ライブデータを取得します。
• lifx://scenes：利用可能なシーンの一覧（名前、UUID）を提供します。ライブデータを取得します。

プロンプト

• effect-creator：エフェクトのパラメーター作成をガイドし、対応するツールコマンドを生成します。
• troubleshooter：ライトの状態を確認し、特定のライトに関する基本的な接続問題の診断を支援します（ライブデータを取得します）。
• selector-helper：ライブデータから利用可能な識別子（ラベル、グループ、場所、ID）を一覧表示し、正確なセレクターの作成を支援します。

その他の機能

• 設定ファイル： ~/.lifx-api-mcp-server.jsonc で設定をカスタマイズできます。
• 環境変数： 設定を上書きできます（例：CONFIG_API_TOKEN、CONFIG_LOG_LEVEL）。
• コンポーネントの無効化： 設定を使用して、ツール、リソース、プロンプトを個別に無効にできます。
• API への直接マッピング： ツールは通常、LIFX API エンドポイントに 1 対 1 で対応します。
• エラー処理： LIFX API の応答と HTTP ステータスコードに基づいてフィードバックを提供します。
• セレクターのサポート： LIFX セレクター（all、id:、label: など）を使用してライトを指定します。
• カラーのサポート： 標準的な LIFX カラーストリングを受け付けます。
• Docker のサポート： Docker コンテナ内で簡単に実行できます。

インストール

LIFX MCP Server は、次のいずれかの方法でインストールして実行できます。

• NPX（最も簡単）
• Docker Hub
• ソースからの Node.js インストール
• ソースからの Docker インストール

インストール：NPX

メモ

NPX の実行には、Node.js（v18 以降）のインストールが必要です。

# Ensure Node.js v18+ is installed
node --version

# Run the server (token should ideally be set via config/env)
npx -y lifx-api-mcp-server@latest [YOUR_LIFX_API_TOKEN_IF_NEEDED]

インストール：Docker Hub

メモ

Docker のインストールが必要です。

# Ensure Docker is installed
docker --version

# Run the server (token should ideally be set via config/env)
# Mount config file (recommended):
docker run --rm -i --network=host \
  -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
  --pull=always furey/lifx-api-mcp-server

# OR pass token via environment variable:
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
  --pull=always furey/lifx-api-mcp-server

# OR pass token as argument (least recommended):
docker run --rm -i --network=host \
  --pull=always furey/lifx-api-mcp-server YOUR_LIFX_API_TOKEN

(furey/lifx-api-mcp-server が異なる場合は、実際の Docker Hub イメージ名に置き換えてください)

インストール：ソースからの Node.js インストール

メモ

Node.js（v18 以降）と npm/yarn のインストールが必要です。

1. リポジトリをクローンします（公開されている場合は、実際の URL に置き換えてください）。

   git clone https://github.com/furey/lifx-api-mcp-server.git # Placeholder
   cd lifx-api-mcp-server
   

2. 依存関係をインストールします。

   npm install
   

3. サーバーを実行します（トークンは、設定または環境変数で指定することを推奨します）。

   node lifx-api-mcp-server.js [YOUR_LIFX_API_TOKEN_IF_NEEDED]
   

インストール：ソースからの Docker インストール

メモ

Docker のインストールが必要です。

1. リポジトリをクローンします。

   git clone https://github.com/furey/lifx-api-mcp-server.git # Placeholder
   cd lifx-api-mcp-server
   

2. Docker イメージをビルドします。

   docker build -t lifx-mcp-server .
   

3. コンテナを実行します（トークンは、設定または環境変数で指定することを推奨します）。

   # Using mounted config file (recommended):
   docker run --rm -i --network=host \
     -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
     lifx-mcp-server
   
   # Using environment variable:
   docker run --rm -i --network=host \
     -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
     lifx-mcp-server
   
   # Using argument (least recommended):
   docker run --rm -i --network=host \
     lifx-mcp-server YOUR_LIFX_API_TOKEN
   

インストールの確認

サーバーが正常に起動すると、次のような出力が表示されます。

[LIFX MCP] LIFX API MCP Server vX.Y.Z starting…
[LIFX MCP] Loading config file: /path/to/.lifx-api-mcp-server.jsonc (or 'No config file found')
[LIFX MCP] Initializing MCP server…
[LIFX MCP] Registering MCP resources…
[LIFX MCP] Total MCP resources registered: X
[LIFX MCP] Registering MCP prompts…
[LIFX MCP] Total MCP prompts registered: Y
[LIFX MCP] Registering MCP tools…
[LIFX MCP] Total MCP tools registered: Z
[LIFX MCP] Creating stdio transport…
[LIFX MCP] Connecting MCP server transport…
[LIFX MCP] LIFX API MCP Server running.

設定

設定ファイルまたは環境変数を使って、サーバーの動作をカスタマイズできます。API トークンは最も重要な設定です。

設定：API トークン（優先順位）

1. 設定ファイル（apiToken キー）： ~/.lifx-api-mcp-server.jsonc を作成または編集します。（推奨）
2. 環境変数（CONFIG_API_TOKEN）： CONFIG_API_TOKEN=YOUR_TOKEN を設定します。
3. コマンドライン引数： スクリプトの実行時に、最初の引数としてトークンを渡します。（推奨度は最低）

設定：設定ファイル

~/.lifx-api-mcp-server.jsonc（または .json）に設定ファイルを作成します。npx -y lifx-api-mcp-server@latest config:create を使用して生成できます。

{
  // Your LIFX Personal Access Token (Required if not using ENV or CLI arg)
  // Get from: https://cloud.lifx.com/settings
  "apiToken": "YOUR_LIFX_API_TOKEN_HERE",

  // Log level: "info" (default) or "verbose" for more detailed logs including rate limits
  "logLevel": "info",

  // --- Optional: Disable specific components ---
  // Add component names here to disable them. Examples:
  // "disabled": {
  //   "tools": ["clean", "cycle"], // Disable specific tools
  //   "resources": ["scenes"],     // Disable the scenes resource
  //   "prompts": true              // Disable all prompts
  // },
  "disabled": {
    "tools": [],
    "resources": [],
    "prompts": []
  },

  // --- Optional: Enable only specific components ---
  // If an 'enabled' array is defined, ONLY those components of that type will be enabled,
  // overriding any 'disabled' settings for that type. Examples:
  // "enabled": {
  //    "tools": ["list-lights", "set-state"], // Only enable these two tools
  //    "resources": ["lights"]                // Only enable the lights resource
  // }
  "enabled": {
    "tools": null,
    "resources": null,
    "prompts": null
  }
}

設定：設定ファイルの生成

デフォルトの設定ファイルを自動生成できます。

# NPX Usage (recommended)
npx -y lifx-api-mcp-server@latest config:create

# Node.js Usage (from source directory)
npm run config:create

# Force overwrite existing file
npx -y lifx-api-mcp-server@latest config:create -- --force
npm run config:create -- --force

# Specify custom path/filename (uses CONFIG_PATH env var)
CONFIG_PATH=/path/to/my-lifx-config.jsonc npm run config:create

これにより、デフォルトでサンプル設定の内容が ~/.lifx-api-mcp-server.jsonc に保存されます。

設定：環境変数による上書き

環境変数を使用して設定を上書きできます（設定ファイルより優先されます）。

使用例：

# Set token and log level via environment variables when using NPX
CONFIG_API_TOKEN=YOUR_TOKEN CONFIG_LOG_LEVEL=verbose npx -y lifx-api-mcp-server@latest

# Same example using Docker
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_TOKEN \
  -e CONFIG_LOG_LEVEL=verbose \
  --pull=always furey/lifx-api-mcp-server

クライアントの設定

lifx-api-mcp-server を起動するように MCP クライアント（Claude Desktop、MCP Inspector など）を設定します。重要： 設定ファイルまたは環境変数で API トークンを設定した場合は、クライアントの設定で引数として渡さないでください。

クライアントの設定：Claude Desktop

1. Claude Desktop をインストールします。

2. claude_desktop_config.json を探すか、作成します。

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

3. サーバーの設定を追加します（必要に応じてパスを調整してください）。

   {
     "mcpServers": {
       "lix-api": {
         // npx がデフォルトの PATH にない場合は、npx の絶対パスを指定します
         "command": "/path/to/your/npx", // または node
         "args": [
           // NPX の例：設定ファイルまたは環境変数で設定した場合、ここにトークンは不要です
           "-y",
           "lifx-api-mcp-server@latest"
   
           // ソースから実行する Node.js の例：設定ファイルまたは環境変数で設定した場合、ここにトークンは不要です
           // "/path/to/lifx-api-mcp-server/lifx-api-mcp-server.js"
         ],
         "env": {
            // 任意：詳細なログ出力を有効にするにはコメントを解除します
            // "CONFIG_LOG_LEVEL": "verbose"
            // 任意：設定ファイルを使わない場合は、環境変数でトークンを設定します
            // "CONFIG_API_TOKEN": "YOUR_LIFX_API_TOKEN"
         }
       }
     }
   }
   

4. Claude Desktop を再起動します。

5. チャットを開始し、ライトとのやり取りを試します（例：「@lix-api list my lights」）。

クライアントの設定：MCP Inspector

MCP Inspector はデバッグに便利です。

# Run MCP Inspector with the LIFX server (NO TOKEN HERE if set in config/env)
npx -y @modelcontextprotocol/inspector npx -y lifx-api-mcp-server@latest

# Open the inspector in your browser (usually http://localhost:5173)

データ保護

• API トークンのセキュリティ： LIFX API トークンを使うと、ライトを操作できます。トークンは秘密にしてください。 コマンドライン引数として渡すよりも、設定ファイル（適切なファイル権限を設定した ~/.lifx-api-mcp-server.jsonc）または環境変数を使うほうが安全です。特に共有環境やログでは注意してください。
• データフロー： リモート LLM（Claude Desktop 経由など）を使用する場合、LLM に送信するプロンプトと、この MCP サーバーから返される結果（ライト名、状態、シーン名）は LLM プロバイダーに送信されます。プライバシーが重要な場合は、ライト／グループ／場所／シーンのラベルに機密情報が含まれていないか注意してください。
• ローカルでの実行： このサーバーはお使いのマシン上でローカルに実行されます。HTTPS 経由で LIFX クラウド API と直接通信します。

チュートリアル

サーバーが実行中で、MCP クライアントに接続されていることを確認してください。label:MyLamp のようなプレースホルダーは、実際のライト／グループ／場所のラベルまたは ID に置き換えてください。

1. 利用可能なライトを確認する（リソース）：

   • @lix-api:lifx://lights
   • ^{➥ lights リソースを使用します}

2. 特定のライトの状態を取得する（リソース）：

   • @lix-api:lifx://light/label:Office Lamp/state
   • ^{➥ light-state リソースを使用します}

3. 利用可能なシーンを取得する（リソース）：

   • @lix-api:lifx://scenes
   • ^{➥ scenes リソースを使用します}

4. セレクターヘルパーを使う（プロンプト）：

   • @lix-api:selector-helper goal: "the lights in the kitchen"
   • ^{➥ selector-helper プロンプトを使用します}

5. エフェクトを作成する（プロンプト）：

   • @lix-api:effect-creator effect_type:breathe selector:all description:"a very slow fade to warm white"
   • ^{➥ effect-creator プロンプトを使用します（応答の指示に従ってください）}

6. ライトのトラブルシューティングを行う（プロンプト）：

   • @lix-api:troubleshooter selector:"id:d073d5xxxxxx"
   • ^{➥ troubleshooter プロンプトを使用します}

7. ライトを一覧表示する（ツール）：

   • 「ライトを一覧表示して」 または 「ライトを一覧表示 selector:all」
   • ^{➥ list-lights ツールを使用します}

8. ライトを点灯する（ツール）：

   • 「Office Lamp という名前のランプを点けて」 または 「状態を設定 selector:label:Office Lamp power:on」
   • ^{➥ set-state ツールを使用します}

9. 色と明るさを設定する（ツール）：

   • 「Kitchen グループのライトを、3 秒かけて明るさ 50％ の青色にして」
   • 「状態を設定 selector:group:Kitchen color:blue brightness:0.5 duration:3」
   • ^{➥ set-state ツールを使用します}

10. 場所のライトを切り替える（ツール）：

    • 「Living Room のライトを切り替えて」 または 「電源を切り替え selector:location:Living Room」
    • ^{➥ toggle-power ツールを使用します}

11. 明るさを上げる（ツール）：

    • 「すべてのライトを 10％ 明るくして」 または 「状態の差分 selector:all brightness:0.1」
    • ^{➥ state-delta ツールを使用します}

12. シーンを有効にする（リソース／ツールからシーン UUID を取得する必要があります）：

    • 「UUID abcdef12-3456-... のシーンを有効にして」
    • 「シーンを有効にする scene_uuid:abcdef12-3456-...」
    • ^{➥ activate-scene ツールを使用します}

Dockerfile

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies cleanly
# Using --omit=dev because devDependencies are not needed in production
RUN npm ci --omit=dev --production --no-fund --no-audit

# Copy the rest of the application code
COPY . .

# Set the entrypoint
ENTRYPOINT ["node", "lifx-api-mcp-server.js"]

# Default command (can be overridden, e.g., with API token if not using config/env)
# CMD ["YOUR_DEFAULT_TOKEN_IF_NEEDED"]

免責事項

• このソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません。ご自身の責任でご使用ください。
• 作者は LIFX（LiFi Labs Inc.）と提携していません。
• 一時的なブロックを避けるため、LIFX API のレート制限（トークンごとに 1 分あたり 120 リクエスト）を把握してください。logLevel が verbose の場合、レート制限に関する情報がログに記録されます。
• このサーバーは一部 AI の支援を受けて生成されており、バグが含まれている場合があります。

サポート

このツールが役に立った場合は、開発者への支援をご検討ください（任意）。

コーヒーをおごる | GitHub スポンサーシップ