Skip to main content
Glama
@mokuichi147/webos-mcp

@mokuichi147/webos-mcp

by Mokuichi147

@mokuichi147/webos-mcp

LG webOS TV を操作する MCP (Model Context Protocol) サーバーです。 SSAP (Second Screen Application Protocol) で TV と直接通信するため、TV 側への追加インストールは不要です。

  • アプリ起動・音量・リモコンキー・マウスポインタ・外部入力の操作

  • 放送の選局、現在の番組・番組表の取得

  • スクリーンショットの取得(LLM が画面を見ながら操作できる)

  • Wake-on-LAN による電源オン

セットアップ

1. MCP クライアントに登録

Claude Desktop / Claude Code などの設定に追加します。

{
  "mcpServers": {
    "webos": {
      "command": "npx",
      "args": ["-y", "@mokuichi147/webos-mcp"]
    }
  }
}

2. TV とペアリング

MCP クライアントから次の順で呼びます。

  1. discover_devices — LAN 上の TV を探索

  2. pair_device — TV 画面に表示される承認ダイアログで「はい」を選ぶと client-key が保存される

CLI から事前にペアリングしておくこともできます。

npx -y @mokuichi147/webos-mcp discover
npx -y @mokuichi147/webos-mcp pair 192.168.1.20 --name living-room

以降は launch_app などのツールをそのまま呼べます。

Related MCP server: sony-bravia-mcp

ツール

TV を操作するツールはすべて device(登録名または IP)を省略可能な引数として受け取ります。省略時は既定デバイスを使います。

デバイス管理

ツール

説明

discover_devices

LAN 上の webOS TV を SSDP で探索

pair_device

TV とペアリングして client-key と MAC アドレスを保存

list_devices

登録済みデバイスの一覧

remove_device

登録を削除

set_default_device

既定デバイスを設定

アプリ

ツール

説明

list_apps

インストール済みアプリの ID とタイトル

get_current_app

前面に表示中のアプリ

launch_app

アプリを起動。params で起動引数を渡せる(例: YouTube の contentTarget に動画 URL)

close_app

アプリを終了(ブラウザ等のシステムアプリは 403 で拒否される)

open_url

TV のブラウザで URL を開く

音量・音声

ツール

説明

get_volume

音量とミュート状態

volume_up / volume_down

音量を 1 段階上下

set_volume

音量を 0〜100 で設定

mute

ミュートの ON / OFF / トグル

get_sound_output / set_sound_output

音声出力先(tv_speaker, external_optical, external_arc, bt_soundbar など)の取得・変更

入力操作

ツール

説明

send_key

リモコンキーを送信(複数指定で順送り)。HOME BACK ENTER UP DOWN PLAY 0〜9 など

send_mouse

マジックリモコンのポインタを相対移動・クリック・スクロール

insert_text / delete_text

フォーカス中のテキストフィールドへ文字入力・削除

media_control

play pause stop rewind fastForward

list_inputs / switch_input

外部入力(HDMI など)の一覧と切替

放送(チューナー)

ツール

説明

watch_tv

アプリや外部入力から放送視聴に切替

list_channels

チャンネル一覧。種別(地デジ / BS / CS / 4K)や局名で絞り込み

get_current_channel

視聴中のチャンネルと放送中の番組(名前・内容・時刻)

get_program_guide

視聴中チャンネルの番組表

set_channel

選局。番号(011 / 41)・局名(NHK総合、部分一致)・channelId のいずれでも指定可

channel_up / channel_down

チャンネル送り

電源・システム

ツール

説明

power_on

Wake-on-LAN で電源オン

power_off

電源オフ(スタンバイ)

get_power_state

電源状態

screenshot

画面のスクリーンショット(960×540 JPEG)を画像として返す

get_settings / set_settings

システム設定(画質・音声など)の取得・変更

show_toast

画面にトースト通知を表示

get_system_info

モデル名などの情報

制限事項

項目

内容

スクリーンショット

解像度は TV 側で 960×540 に固定。DRM 保護された動画(Netflix / Prime Video など)の再生中は黒く写る

電源オン

SSAP では不可能なため Wake-on-LAN を使う。TV 側で「ネットワーク経由で電源オン」等の設定が必要。power_off 直後は TV がシャットダウン中のため get_power_state は接続エラーを返す

放送情報

get_current_channel / get_program_guide は放送視聴中のみ取得できる。番組表は視聴中チャンネルの分のみ。set_channel 系は必要に応じて自動で放送視聴に切り替える

文字入力

システムの仮想キーボードがテキストフィールドにフォーカスしている場合のみ動作する(ブラウザなど)。YouTube のようにアプリ独自のキーボードを持つアプリには入力できない。ブラウザでキーボードが出ない場合は send_mouse でフィールドをクリックする

マウス座標

1920×1080 相当の相対移動(screenshot の座標の 2 倍)。絶対位置へ動かすには大きな負の値で左上に寄せてから移動する

設定変更

set_settings は WRITE_SETTINGS 権限が必要。署名なしマニフェストで登録された TV では 401 になる(後述)

再生制御

media_control はアプリ依存。YouTube で動作確認済み

設定ファイル

デバイス情報は ~/.config/webos-mcp/devices.json(XDG_CONFIG_HOME を尊重)に保存されます。

{
  "version": 1,
  "defaultDevice": "living-room",
  "devices": {
    "living-room": {
      "name": "living-room",
      "host": "192.168.1.20",
      "id": "560ad548-....",
      "model": "OLED65B6MJA",
      "clientKey": "...",
      "mac": "D0:CD:BF:...",
      "wifiMac": "70:3E:76:..."
    }
  }
}

CLI オプション / 環境変数

オプション

環境変数

説明

--device <name>

WEBOS_DEVICE

既定デバイス名

--host <ip>

WEBOS_HOST

設定ファイルを使わず直接接続する TV

--client-key <key>

WEBOS_CLIENT_KEY

--host と併用する client-key

--config-dir <dir>

WEBOS_CONFIG_DIR

設定ディレクトリ

--debug

WEBOS_MCP_DEBUG=1

デバッグログを stderr に出力

ファームウェアとマニフェスト

webOS 26 以降のファームウェアは、従来のリモコンアプリ由来の署名付きマニフェストを 403 Pairing rejected: blacklisted certificate detected で拒否します。 本サーバーはまず署名付きで登録を試み、拒否された場合のみ署名なしマニフェストで再登録します。 署名なしでは WRITE_SETTINGS など一部の権限が付与されないため、set_settings が 401 になります。

開発

npm install
npm run build
node dist/cli.js discover

ロードマップ

  • SSAP による探索・ペアリング・アプリ/音量/キー操作

  • 放送・スクリーンショット・Wake-on-LAN

  • TV 側 Companion アプリ(Luna API ブリッジ)

  • SSAP / Luna の自動切替と Luna 固有ツール(高解像度キャプチャ、設定変更など)

License

MIT

Available Tools

39 tools
channel_downチャンネルを下げるB

前のチャンネルへ切り替える。

Inputs: device.

channel_upチャンネルを上げるC

次のチャンネルへ切り替える。

Inputs: device.

close_appアプリ終了B

指定したアプリを終了する。

Inputs: appId (required), device.

delete_text文字削除A

フォーカス中のテキストフィールドからカーソル前の文字を削除する。

Inputs: count, device.

discover_devicesTV を探索A
Read-only

LAN 上の LG webOS TV を SSDP で探索し、IP・名前・モデルを返す。

Inputs: timeoutMs.

get_current_app前面アプリを取得A
Read-only

現在前面に表示されているアプリの ID を返す。

Inputs: device.

get_current_channel現在のチャンネルと番組A
Read-only

視聴中のチャンネルと、放送中の番組名・内容・開始/終了時刻を返す。放送視聴中でない場合はその旨を返す。

Inputs: device.

get_power_state電源状態A
Read-only

TV の電源状態を返す(Active / Active Standby / Screen Off など)。TV がスタンバイで応答しない場合はその旨を返す。

Inputs: device.

get_program_guide番組表A
Read-only

視聴中チャンネルの番組表(これから放送される番組の一覧)を返す。放送視聴中でない場合はその旨を返す。

Inputs: device.

get_settings設定を取得A
Read-only

システム設定を取得する。例: category=picture keys=[brightness,contrast,backlight,color,pictureMode] / category=sound keys=[soundMode]。

Inputs: keys (required), category (required), device.

get_sound_output音声出力先を取得A
Read-only

現在の音声出力先を返す(tv_speaker, external_optical, external_arc, bt_soundbar, headphone など)。

Inputs: device.

get_system_infoシステム情報A
Read-only

TV のモデル名・webOS バージョン等を返す。

Inputs: device.

get_volume音量取得A
Read-only

現在の音量とミュート状態を返す。

Inputs: device.

insert_text文字入力A

TV 上でフォーカスされているテキストフィールド(検索欄など)に文字列を入力する。入力欄が表示されていないと失敗する。enter=true で入力後に確定する。

Inputs: text (required), enter, device, replace.

launch_appアプリ起動A

アプリ ID(例: netflix, youtube.leanback.v4, com.webos.app.hdmi1)でアプリを起動する。任意で起動パラメータを渡せる。

Inputs: appId (required), device, params.

list_appsアプリ一覧A
Read-only

TV にインストールされているアプリの ID とタイトルを返す。launch_app にはこの id を渡す。

Inputs: device, includeHidden.

list_channelsチャンネル一覧B
Read-only

受信可能なチャンネル一覧を返す。type で放送種別を絞り込める(例: Terrestrial=地デジ, BS, CS, UHD=4K)。set_channel には number / name / channelId のいずれでも渡せる。

Inputs: type, query, device, includeSkipped.

list_devices登録済みデバイス一覧A
Read-only

devices.json に保存されているデバイスと既定デバイスを返す。

Inputs: no named parameters.

list_inputs外部入力一覧A
Read-only

HDMI などの外部入力の ID・ラベル・接続状態を返す。switch_input にはこの id を渡す。

Inputs: device.

media_control再生制御A

再生・一時停止・停止・巻き戻し・早送りを送る。アプリによっては対応していない。

Inputs: action (required), device.

muteミュート切替A

ミュートを ON/OFF する。mute 省略時はトグル。

Inputs: mute, device.

open_urlURL をブラウザで開くA

TV のブラウザで URL を開く。

Inputs: url (required), device.

pair_deviceTV とペアリングA

指定した IP の TV に接続してペアリングする。TV 画面に表示される承認ダイアログでユーザーが「はい」を選ぶまで待機し、client-key を保存する。

Inputs: host (required), name, makeDefault.

power_off電源オフA
Destructive

TV の電源を切る(スタンバイ)。

Inputs: device.

power_on電源オン (Wake-on-LAN)A

Wake-on-LAN で TV の電源を入れる。pair_device 時に保存した MAC アドレスを使う(mac パラメータで上書き可)。TV 側で「ネットワーク経由で電源オン」等の設定が有効である必要がある。

Inputs: mac, device.

remove_deviceデバイス登録を削除A
Destructive

保存済みのデバイス(client-key を含む)を削除する。

Inputs: name (required).

screenshotスクリーンショットA
Read-only

TV 画面のスクリーンショット (960x540 JPEG) を取得する。現在の表示内容を確認してから操作したいときに使う。DRM 保護された動画(Netflix / Prime Video 等の再生中)は黒く写る。

Inputs: device.

send_keyリモコンキー送信B

リモコンのボタン操作を送る。複数指定すると順に送信する。使用可能なキー: LEFT, RIGHT, UP, DOWN, ENTER, BACK, EXIT, HOME, MENU, INFO, GUIDE, DASH, VOLUMEUP, VOLUMEDOWN, MUTE, CHANNELUP, CHANNELDOWN, PLAY, PAUSE, STOP, REWIND, FASTFORWARD, RECORD, RED, GREEN, YELLOW, BLUE, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ASTERISK, CC, POWER, CLICK

Inputs: keys (required), device.

send_mouseマウス操作A

TV のマウスポインタを操作する。move は相対移動(画面は 1920x1080 相当。screenshot の 960x540 座標の 2 倍)。絶対位置に置きたいときは先に大きな負の値で左上に寄せてから移動する(例: move -3000,-3000 → move 960,512)。ブラウザ等でテキスト欄をクリックして仮想キーボードを出すときに使う。

Inputs: action (required), dx, dy, device.

set_channel選局B

チャンネルを切り替える。channel には番号(例: 011, 41)、局名(例: NHK総合, テレ東)、channelId のいずれかを指定。放送視聴中でなければ自動で切り替える。

Inputs: channel (required), device.

set_default_device既定デバイスを設定A

device パラメータ省略時に使うデバイスを設定する。

Inputs: name (required).

set_settings設定を変更B

システム設定を変更する。例: category=picture settings={backlight: 60}。TV のファームウェアによっては WRITE_SETTINGS 権限がなく 401 になる。

Inputs: category (required), settings (required), device.

set_sound_output音声出力先を変更C

音声出力先を切り替える。

Inputs: output (required), device.

set_volume音量を設定B

音量を 0〜100 で設定する。

Inputs: volume (required), device.

show_toastトースト通知B

TV 画面にトースト通知を表示する。

Inputs: message (required), device.

switch_input外部入力を切替C

外部入力を切り替える(例: HDMI_1, HDMI_2)。

Inputs: inputId (required), device.

volume_down音量を下げるA

音量を 1 段階下げる。

Inputs: device.

volume_up音量を上げるB

音量を 1 段階上げる。

Inputs: device.

watch_tv放送視聴に切替A

アプリや外部入力からテレビ放送(チューナー)の視聴に切り替える。

Inputs: device.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 39 tools

    Disambiguation3/5

    Most tools cleanly separate domains like device management, apps, volume, inputs, and channels. However, send_key overlaps with media_control, volume controls, power_off, and channel_up/down, which creates ambiguity about whether to use the generic key sender or the specialized wrappers.

    Naming Consistency4/5

    The vast majority of tools follow a clear snake_case verb_noun pattern: list_apps, get_volume, set_channel, launch_app. A few exceptions like mute, screenshot, volume_up, channel_down, and power_on break the pattern slightly, but the overall convention is consistent and readable.

    Tool Count2/5

    39 tools is well beyond the typical well-scoped range and creates significant selection burden for an agent. The count is partially justified by the breadth of TV control, but many tools duplicate what send_key already does, making the surface feel heavier than necessary.

    Completeness5/5

    The surface is remarkably complete for an LG webOS TV remote: discovery, pairing, device management, power, apps, inputs, audio, channels, program guide, settings, text input, mouse control, screenshots, and toasts are all covered. Agents can execute the full lifecycle from pairing to everyday control without obvious dead ends.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Lets MCP clients and the command line control LG webOS TVs directly over the local network, discovering and pairing TVs and then launching apps, switching inputs, playing YouTube videos, adjusting volume, pressing remote keys, showing messages, and powering the TV on or off.
      18
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables agents and operators to control LG webOS TVs over a LAN through MCP, including apps, remote keys, pointer, text, power, discovery, route learning, and visual fallback.
      17
      1
      MIT