Skip to main content
Glama
mcp-server-shieldtv
by SDNick484

mcp-server-shieldtv

CI

An MCP server for the NVIDIA Shield TV, built on the Android TV Remote protocol v2 (the same protocol the Google TV phone app uses). It lets an MCP client such as Claude press remote keys, launch apps, wake or sleep the Shield, and read its power state and foreground app.

Status. Pairing, get_status, keys, launch_app, set_power and the ADB tools were verified on a real Shield (remote service 7.00) in 2026-10. The features added since (pairing retries, reconnect and rediscovery hardening, dry run, doctor, resources and prompts, HTTP, the Alpine service) are verified against the simulator only, a wire-level fake that the real protocol library pairs and connects with. Verification status lists every protocol assumption and whether a Shield has confirmed it; HARDWARE_VALIDATION.md is the checklist.

It's one of four sibling servers with the same conventions (dry run, doctor, typed results, Streamable HTTP behind Cloudflare Access): mcp-server-onkyo, mcp-server-harmony and mcp-server-sofabaton.

This is not an official NVIDIA project, and NVIDIA publishes no MCP server for the Shield.

Why this protocol

Remote protocol v2 (this project)

ADB

Setup

One-time pairing with an on-screen code

Enable Network debugging on the Shield

Good for

D-pad, media keys, app launch, power/app state

Deep device inspection

Risk if exposed to an LLM

Bounded: it can only press keys

High: adb shell is arbitrary code execution

Three optional ADB tools do what the remote protocol can't: get_now_playing, get_remotes and reboot_shield. They are off until you run adb-setup, and they run only fixed commands; the server never exposes a raw shell (see ADB tools).

Related MCP server: ios-control-mcp

Install

python -m venv ~/.venvs/shieldtv && . ~/.venvs/shieldtv/bin/activate
pip install mcp-server-shieldtv

From source instead (for the newest code, or to run the tests):

git clone https://github.com/SDNick484/mcp-server-shieldtv.git && cd mcp-server-shieldtv
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]" && pytest

Requires Python 3.11+.

Pair with your Shield (once)

The Shield and the machine running the server must be on the same network, and the machine must be able to reach the Shield on these ports:

Port

Used for

TCP 6466

Remote control (every tool call)

TCP 6467

Pairing (only during pair)

UDP 5353 (mDNS)

discover, and pair without --host

TCP 5555

ADB, only if you enable the ADB tools with adb-setup

A firewall, a guest network, or a separate IoT VLAN between the two will show up as "can't reach the Shield".

mcp-server-shieldtv discover            # optional: list Android TV devices via mDNS
mcp-server-shieldtv pair                # finds the Shield, or: pair --host 192.168.1.50

A code appears on the TV; type it into the terminal. A typo, a rejected code or Cancel on the TV starts over with a new code (three tries). Pairing generates a client certificate and key under ~/.config/mcp-server-shieldtv/ (override with SHIELDTV_CONFIG_DIR) and saves the Shield's address, name and MAC in config.json. The MAC is how the server finds the Shield again if its address changes. Unusable old credentials are set aside (cert.pem.broken) and replaced. A running server notices a new pairing and reconnects with it; it doesn't need a restart.

Then check everything between this machine and the Shield:

mcp-server-shieldtv doctor
Shield 192.168.1.50
   ok config    paired with SHIELD Android TV (MAC xx:xx:xx:xx:B2:C3) at x.x.x.50; credentials load and are private
   ok tcp       ports 6466 and 6467 accept connections
   ok identity  SHIELD Android TV, MAC xx:xx:xx:xx:B2:C3
   ok session   NVIDIA SHIELD Android TV (remote service <version>); on, com.google.android.tvlauncher in front, ...

doctor checks each layer in order and stops at the first failure, saying what it means and which HARDWARE_VALIDATION.md step covers it. It never presses a key, launches anything or pairs. Output is redacted (addresses, MACs) unless --no-redact.

Treat cert.pem and key.pem like a password. Anyone who has them can control your Shield. The directory is created 0700 and the files 0600, and .gitignore excludes them. To revoke access, remove the device from the Shield's settings and re-pair.

WSL2 note: mDNS discovery needs mirrored networking (networkingMode=mirrored in %UserProfile%\.wslconfig, then wsl --shutdown). Otherwise pass --host.

ADB tools (optional)

The remote protocol knows which app is in front, but not what it's playing, whether your Bluetooth remotes work, or how to reboot. ADB can do all three. To enable the ADB tools:

  1. On the Shield: Settings > Device Preferences > About, select Build seven times, then Developer options > Network debugging on.

  2. Run mcp-server-shieldtv adb-setup (after pair). The TV asks "Allow USB debugging?": tick "Always allow from this computer" and choose Allow.

adb-setup creates its own ADB key (adbkey, adbkey.pub, 0600) next to the pairing files and sets "adb": true in config.json. The ADB key grants a shell on the Shield; guard it more carefully than the pairing files. To revoke it, use Developer options > Revoke USB debugging authorizations.

get_now_playing reports, checked on a real Shield: the app, title, subtitle (the artist for music, the channel for live TV), play state, and position. Live TV (YouTube TV, Sling) reports no position, since its "position" is an offset into the stream. Music played from YouTube Music shows up as the YouTube app. Duration and album aren't available this way. A title that contains ", " can rarely split wrong (the system prints title and artist joined by ", ").

get_remotes lists Bluetooth remotes (a Harmony hub shows up as "Harmony Keyboard") (every paired input device, even ones that haven't connected since the Shield started) as working, disconnected (normal when not in use), or stuck: Bluetooth says it is connected, but Android never created its input device, so its buttons do nothing. This happened to both remotes on a real Shield after a reboot. The fix for a Harmony hub is to press Off and start the activity again.

reboot_shield notes which remotes work, restarts the Shield, and waits until it has booted (about 35 seconds on a real Shield) plus 20 seconds for remotes that reconnect on their own. It reports any remote that came back stuck, with the fix, and any that worked before but hasn't reconnected yet. A Harmony hub doesn't reconnect until a button is pressed, so expect it to be listed that way; if it then does nothing, get_remotes says whether it's stuck. The whole call takes about a minute. It is marked destructive, so MCP clients ask before running it.

Use it with an MCP client

{
  "mcpServers": {
    "shieldtv": { "command": "/path/to/mcp-server-shieldtv/.venv/bin/mcp-server-shieldtv" }
  }
}

For Claude Code: claude mcp add shieldtv -- /path/to/.venv/bin/mcp-server-shieldtv.

HTTP and Cloudflare Access

To share one server between Claude Code, Claude Desktop and the mobile app, run it as a service and reach it through a Cloudflare Tunnel with Access in front:

CF_ACCESS_TEAM_DOMAIN=<team>.cloudflareaccess.com CF_ACCESS_AUD=<aud tag> \
  mcp-server-shieldtv --http --public-host mcp.example.com      # 127.0.0.1:8712/shieldtv/mcp

Flag

Variable

Default

--bind

MCP_HTTP_BIND

127.0.0.1

--port

MCP_HTTP_PORT

8712 (Onkyo 8711, Harmony 8713)

--path

MCP_HTTP_PATH

/shieldtv/mcp

--public-host

MCP_PUBLIC_HOSTS

none: only loopback Host headers pass

CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD

none: no Access checks

MCP_ALLOWED_EMAILS

anyone Access lets in

With Access configured, every request needs a valid Cf-Access-Jwt-Assertion: the signature (the team's published keys), audience, issuer, expiry, and the email allow-list if set. Anything else gets a plain 403. The server refuses to start on a non-loopback address without Access unless you pass --insecure-no-auth (for trusted-LAN testing only). It also checks Host and Origin (DNS-rebinding protection), including on --bind 0.0.0.0. GET /healthz answers without auth. src/shieldtv_mcp/remote.py is identical in all four servers.

As a service on Alpine (Proxmox LXC)

sh deploy/alpine/install.sh                      # as root; or: install.sh /path/to/checkout
su -s /bin/sh mcp-shieldtv -c 'SHIELDTV_CONFIG_DIR=/var/lib/mcp-server-shieldtv \
  /opt/mcp-server-shieldtv/venv/bin/mcp-server-shieldtv pair --host <shield ip>'
vi /etc/mcp-server-shieldtv/env                  # HTTP and Access settings
rc-update add mcp-server-shieldtv default && rc-service mcp-server-shieldtv start

Path

Owner, mode

Holds

/opt/mcp-server-shieldtv/venv

root, 0755

The code

/etc/mcp-server-shieldtv/env

root:mcp-shieldtv, 0640

HTTP and Access settings

/var/lib/mcp-server-shieldtv/

mcp-shieldtv, 0700 (files 0600)

cert.pem, key.pem, adbkey, config.json

/var/log/mcp-server-shieldtv/server.log

mcp-shieldtv, 0750

Logs, redacted

/etc/init.d/mcp-server-shieldtv

root, 0755

OpenRC script (supervise-daemon, restarts on exit)

The credentials live in /var/lib, owned by the unprivileged mcp-shieldtv user, because they're the service's own: pair runs as that user, and the server rewrites config.json when the Shield moves. Every dependency has a musl wheel, so nothing compiles. deploy/alpine/smoke-test.sh runs the whole install in a python:3.12-alpine container against the simulator, and CI runs it on every push. To point it at a particular Shield without editing config.json, pass the host as an environment variable: claude mcp add shieldtv -e SHIELDTV_HOST=192.168.1.50 -- .... That Shield must already be paired with the same credentials (pair --host <ip> once per Shield; note that pair also saves its host as the default in config.json).

Configuration

Setting

Default

What it does

SHIELDTV_HOST

(from config.json)

The Shield's IP address or hostname

SHIELDTV_CONFIG_DIR

$XDG_CONFIG_HOME/mcp-server-shieldtv

Where the certificate, key and config.json live

XDG_CONFIG_HOME

~/.config

Standard base directory, used when SHIELDTV_CONFIG_DIR is unset

SHIELDTV_DRY_RUN

off

Read the Shield, send nothing that changes anything (serve --dry-run)

SHIELDTV_DEBUG

off

Log the protocol traffic to stderr (--debug)

SHIELDTV_LOG_UNREDACTED

off

Show LAN addresses and MACs in logs (--no-redact); keys and tokens stay hidden

config.json (written by pair, safe to edit by hand):

Key

What it does

host

The Shield's address, saved by pair (and updated if the Shield moves)

name, mac

The Shield's name and MAC, read from its certificate by pair

apps

Extra or overriding app names for launch_app (see below)

adb

true once adb-setup succeeds; enables the ADB tools

port, pairing_port

6466 and 6467; other values are for the simulator

Problems in config.json (invalid JSON, a bad app entry) are logged at startup and shown by doctor, and only the bad part is ignored.

When the host is set in more than one place, the most specific wins: pair --host, then SHIELDTV_HOST, then config.json.

Tools

Tool

What it does

get_status

Reachability, power (on/standby), foreground app, volume (null when not reported), device info; while unreachable, stale: true with as_of and error

list_apps

The app names launch_app accepts

send_key

Press an allow-listed remote key, optionally repeated 1-10 times (see below)

launch_app

Launch an allow-listed app by friendly name, and confirm it reached the foreground

set_power

Wake (on) or sleep (off) using WAKEUP/SLEEP, not the POWER toggle

get_now_playing

App, title, subtitle (artist or channel), play state and position. Needs adb-setup

get_remotes

Each Bluetooth remote and whether it works, with a fix for stuck ones. Needs adb-setup

reboot_shield

Restart the Shield, wait until it's back, then check the remotes. Needs adb-setup

Every tool returns structured content with a published output schema. The actions (send_key, launch_app, set_power, and reboot_shield's first fields) return the same ActionResult shape as the sibling servers:

{"shield": "SHIELD Android TV", "outcome": "done",
 "detail": "Launched netflix (com.netflix.ninja is in the foreground)",
 "sent": ["app_link https://www.netflix.com/title"], "warnings": []}

outcome is done, unchanged (e.g. set_power off while already in standby: nothing is sent) or dry_run. Failures are MCP errors with a sentence that says what to do.

Dry run (serve --dry-run, call --dry-run or SHIELDTV_DRY_RUN=1) reads the Shield and validates every call as usual, but sends nothing; results say what would have been sent.

Resources and prompts

Resources are context a client attaches (in Claude Code: @shieldtv:shieldtv://apps). Reading them sends nothing to the Shield.

Resource

What it holds

shieldtv://apps

The apps launch_app accepts: link, package, and whether each is a default or from config.json

shieldtv://keys

The keys send_key accepts, and the ones left out on purpose, with why

Prompts are workflows you pick (in Claude Code: /mcp__shieldtv__watch netflix).

Prompt

Arguments

Does

watch

app, what

Wakes the Shield, opens the app, navigates with the D-pad while asking you what's on screen

remotes_not_working

Runs get_remotes and repeats its advice; doesn't reboot unless you ask

Movie night across servers

The servers don't know about each other: each works alone, and a client with several connected composes them. With all four connected, "movie night in the theater: Plex on the Shield, receiver in Dolby Surround at 45" becomes (tool names as of these versions):

harmony.start_activity   activity="Watch Shield"          # TV and receiver on, inputs switched
shieldtv.launch_app      app="plex"
onkyo.set_listening_mode receiver="Theater" mode="dolby-surround"
onkyo.set_volume         receiver="Theater" level=45      # capped server-side if above the cap

What makes this safe to hand to a model is that limits live in each server, not in the prompt: only allow-listed keys and apps here, and the volume cap and never-guess-a-receiver rule in Onkyo.

Allowed keys: HOME, BACK, MENU, DPAD_UP/DOWN/LEFT/RIGHT/CENTER, MEDIA_PLAY_PAUSE, MEDIA_PLAY, MEDIA_PAUSE, MEDIA_STOP, MEDIA_NEXT, MEDIA_PREVIOUS, MEDIA_REWIND, MEDIA_FAST_FORWARD, VOLUME_UP, VOLUME_DOWN, VOLUME_MUTE.

Apps

Default apps, each checked on a real Shield: youtube, youtube-tv, netflix, prime-video, disney+, hulu, plex, spotify.

Apps launch through deep links: https links, or an app's own scheme (plex://, spotify:) where the https link would go to a browser instead. On the Shield (remote service 7.x), a bare package name is sent as market://launch?id=<package>, which the Shield rejects and then drops the connection. launch_app waits for the app to reach the foreground (up to 10s) and returns an error that says what happened if it doesn't: the request was rejected, or it was accepted but nothing opened (the app isn't installed, or no app handles the link; the TV shows "You don't have an app that can do this").

Add your own apps

Edit ~/.config/mcp-server-shieldtv/config.json:

{
  "host": "192.168.1.50",
  "apps": {
    "crunchyroll": { "link": "https://www.crunchyroll.com", "package": "com.crunchyroll.crunchyroid" },
    "example": "https://example.com/tv"
  }
}

An entry is either a link, or { "link", "package" }. Adding the package is recommended: launch_app then confirms that exact app opened, and get_status shows the friendly name. Without it, any app other than the home screen coming to the front counts as success. Names are case-insensitive, and an entry with the same name as a default replaces it. Restart the server (or your MCP client) to pick up changes.

Finding the link and package: open the app on the Shield, then call get_status (or ask "what app is open on the Shield?"); current_app_package is the package. For the link, try the service's website address (https://www.<service>.com). With ADB enabled, Android can tell you which app a link opens without launching anything:

adb shell cmd package query-activities --brief -a android.intent.action.VIEW \
  -c android.intent.category.BROWSABLE -d 'https://tv.youtube.com'

A result of com.google.android.tv.frameworkpackagestubs/.Stubs$BrowserStub means "no app" (the TV shows "You don't have an app that can do this"). If the stub is listed alongside the app, the app usually still opens, but its own scheme (if it has one) avoids the ambiguity.

Safety design

  • Keys are an allow-list. The tool schema is an enum, and the client re-checks it. POWER, SEARCH (starts voice capture), SETTINGS, MUTE (Android's microphone mute), raw numeric key codes, and the library's text: typing are not available.

  • Apps are an allow-list. Only names in list_apps can be launched.

  • No shell and no arbitrary key codes, so a prompt-injected model has a small blast radius. ADB is off by default. When enabled, the ADB tools take no arguments and run only constant commands (dumpsys media_session, dumpsys bluetooth_manager, dumpsys input, getprop sys.boot_completed, /proc/uptime), plus ADB's own reboot service. Code that tries any other command is refused, so nothing the model writes reaches the Shield's shell.

  • reboot_shield is the only tool marked destructive: it interrupts playback, so clients should confirm with you first.

  • Credentials are private (0600) and never logged. Logs go to stderr because stdout belongs to the MCP transport.

  • Tools carry titles and MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can decide what needs confirmation.

Behavior notes

  • The server keeps one long-lived connection and caches pushed state. If the Shield is asleep or offline at startup it retries in the background (1 s doubling to 60 s), and tool calls return a clear "can't reach the Shield" message in the meantime. Each attempt is bounded (15 s), so a Shield that accepts the connection but never starts a session can't hang the server.

  • While disconnected, get_status still shows the last known values, marked stale: true, with as_of (when they arrived) and error (why it isn't reachable).

  • If the Shield moves to another address (DHCP), after 60 s unreachable the server looks for it over mDNS and checks each candidate's certificate for the MAC that pair saved. Only an exact match is adopted, and saved to config.json. Any other device is never guessed at.

  • If the Shield stops trusting the certificate (unpaired on the TV, factory reset), the error says to re-run pair, and the running server picks up the new pairing by itself.

  • Volume keys act on whatever the Shield is configured to control (the Shield itself, HDMI-CEC, or IR), so results depend on your setup. When volume goes to a TV or receiver over CEC, the Shield doesn't report a level, and get_status returns volume: null.

Troubleshooting

The server's errors are written to be actionable, so the model will usually relay one of these:

"Not paired with a Shield yet." No host or credentials were found. Run mcp-server-shieldtv pair. If you did pair, check that the server and pair use the same SHIELDTV_CONFIG_DIR (an MCP client may launch the server with a different environment).

"The Shield rejected our pairing." The Shield no longer trusts this certificate, typically after a factory reset or after removing the device under the Shield's remote/connected-device settings. Run pair again; a running server reconnects by itself.

"Can't connect: the pairing files ... can't be used." cert.pem or key.pem is damaged. Run pair again; it sets the old files aside.

"Can't reach the Shield at ..." The server is paired but has no connection. The Shield may be asleep, rebooting, or off the network, its IP may have changed (a DHCP reservation helps), or TCP 6466 may be blocked (see the port table above). The server keeps retrying in the background, so the next call may succeed without a restart. If the address changed and config.json has the Shield's mac (saved by pair since this version), the server finds it again by itself; otherwise re-pair with the new address. doctor tells these cases apart.

"The connection to the Shield dropped; try again in a moment." The connection closed during the command. The library reconnects on its own; retry.

"The Shield rejected the launch request ..." The app entry is a bare package name (or a link the Shield refuses). Use an https link; see Apps.

"The Shield accepted ..., but the foreground app didn't change" The app is probably not installed, or nothing on the Shield handles that link. A very slow cold start can also do this; the next call then reports the app as already open.

pair says "No input to read the code from". It was run without a terminal (for example through a tool that doesn't attach one). Run it in a regular terminal.

discover (or pair without --host) finds nothing. mDNS doesn't cross most VLANs or guest networks, and on WSL2 it needs mirrored networking (see above). Pass --host <ip>; the Shield shows its IP in its network/about settings, and your router's client list has it too.

Server logs (connection attempts, retries, auth failures) go to stderr, which most MCP clients save in their own logs. Running mcp-server-shieldtv in a terminal shows them directly; it waits for MCP messages on stdin, so stop it with Ctrl+C.

A session against the simulator

simulate runs a simulated Shield: TLS on two ports, speaking Android TV Remote v2 the way androidtvremote2 does. The real library pairs and connects with it. Pair with it exactly as with a real one (the code "on the TV" is printed by the simulator), or pass --paired:

$ mcp-server-shieldtv simulate --config-dir /tmp/sim        # terminal 1
  ...
  The TV shows the pairing code: 3B26B3

$ export SHIELDTV_CONFIG_DIR=/tmp/sim                         # terminal 2
$ mcp-server-shieldtv pair --host 127.0.0.1
Pairing with SHIELD Android TV (00:04:4B:A1:B2:C3). A code will appear on the TV screen.
Enter the code shown on the TV: 3B26B3
Paired and connected: NVIDIA SHIELD Android TV

$ mcp-server-shieldtv call launch_app app=netflix
{ "shield": "SHIELD Android TV", "outcome": "done",
  "detail": "Launched netflix (com.netflix.ninja is in the foreground)",
  "sent": ["app_link https://www.netflix.com/title"], "warnings": [] }

$ mcp-server-shieldtv call set_power state=off
{ ..., "outcome": "done", "detail": "The Shield is in standby", "sent": ["KEYCODE_SLEEP"] }

$ mcp-server-shieldtv call set_power state=off
{ ..., "outcome": "unchanged", "detail": "The Shield is already in standby", "sent": [] }

$ mcp-server-shieldtv call launch_app app=hulu
Error executing tool launch_app: The Shield accepted https://www.hulu.com/welcome, but the
foreground app didn't change within 10s (still com.netflix.ninja). The app may not be
installed, or no installed app handles that link; the TV may be showing an error. The Shield
is in standby, which may be why: wake it with set_power first.

(Lines wrapped, some fields elided with ....) What the simulator does and where each behavior comes from (the library's client code, the owner's Shield, or invented for a test) is listed at the top of src/shieldtv_mcp/sim/fake_shield.py.

Development

pip install -e ".[dev]"
pytest -q           # ~200 tests, ~15 s, no Shield needed
ruff check . && ruff format --check .
mypy                # strict type checking of src/

Tests

Cover

test_config.py

Allow-lists (checked against the protocol's own key enum), settings, config problems

test_client.py

Connection lifecycle and state against FakeRemote, a stand-in for the library

test_wire.py

The real library against the simulated Shield: pairing (typo, rejection, Cancel, Shield gone), session, drops, garbled frames, sleep, stale state, unpairing, re-pair pickup, an address change (127.0.0.2 to .3)

test_tools.py, test_resources.py

The MCP contract: schemas, annotations, ActionResults, errors, dry run, resources, prompts

test_adb.py

ADB parsers on real dumpsys output; only constant commands reach the shell

test_tooling.py, test_cli.py

doctor, simulate, call, argument parsing

test_http_tools.py, test_remote.py

Streamable HTTP end to end; Access JWTs (valid, expired, wrong audience, wrong issuer, missing) with locally generated keys

test_stdio.py

The installed entry point over stdio

test_assumptions.py

Every assumption is cited by code, and listed here and in HARDWARE_VALIDATION.md

CI runs it all on Python 3.11-3.14, plus the Alpine smoke test. npx @modelcontextprotocol/inspector mcp-server-shieldtv browses tools, resources and prompts by hand. docs/ADB_TOOLS.md reviews the ADB tools and proposes read-only additions (design only).

Verification status

Hardware-verified means seen on the owner's Shield (what was seen is in each assumption's note in src/shieldtv_mcp/assumptions.py). Simulator-only means the simulator implements it and nothing has confirmed it.

Assumption

Confidence

Status

S-PAIRING

high

hardware-verified

S-REMOTE-HANDSHAKE

high

hardware-verified

S-TLS-REJECT

medium

simulator-only

S-CERT-MAC

medium

simulator-only

S-MDNS

high

simulator-only

S-RECONNECT

high

hardware-verified

S-SLEEP-CONNECTION

medium

simulator-only

S-MARKET-REJECT

high

hardware-verified

S-LINK-UNHANDLED

high

hardware-verified

S-WAKE-ANY-KEY

high

hardware-verified

S-CEC-VOLUME

high

hardware-verified

S-APP-LINKS

high

hardware-verified

S-DUMPSYS-MEDIA

high

hardware-verified

S-LIVE-TV-PACKAGES

medium

simulator-only

S-STUCK-REMOTES

high

hardware-verified

S-REBOOT-TIME

high

hardware-verified

test_assumptions.py fails if this table and assumptions.py disagree.

Roadmap

  • Hardware validation of this branch (HARDWARE_VALIDATION.md)

  • The ADB proposals in docs/ADB_TOOLS.md, once their outputs are captured

  • Several Shields from one server, by name (as the sibling servers do)

  • Publish to PyPI and the MCP registry

License

MIT. See LICENSE.

Available Tools

8 tools
shield_get_now_playingGet what's playingA
Read-only

Report what is playing: app, title, subtitle (artist or channel), play state, position in seconds.

<use_case> Retrieve playback metadata and playback state of media currently active on the Shield. </use_case>

<important_notes>

  • Requires ADB connection established via mcp-server-shieldtv adb-setup.

  • position_s is null for live streaming TV. </important_notes>

Inputs: no named parameters. Returns: app, state, title, subtitle, +2 more

shield_get_remotesCheck Bluetooth remotesA
Read-only

List the Shield's Bluetooth remotes (e.g. a Harmony hub) and whether each works.

<use_case> Diagnose unresponsive physical or hub remotes paired to the Shield over Bluetooth. </use_case>

<important_notes>

  • Requires ADB connection (mcp-server-shieldtv adb-setup).

  • Reports "stuck" state when a connected remote stops sending button events (common after sleep/reboot). </important_notes>

Inputs: no named parameters. Returns: advice, remotes

shield_get_statusGet Shield statusA
Read-only

Start here. Query Shield TV power state, reachability, foreground app, and volume.

<use_case> Inspect Shield TV power, connectivity, active foreground package, and volume before issuing commands. </use_case>

<important_notes>

  • When unreachable, stale is true and values represent last known state.

  • Video output routes to the Onkyo AVR input 'strm-box'. </important_notes>

Inputs: no named parameters. Returns: host, name, as_of, error, +9 more

shield_launch_appLaunch an appA
Idempotent

Launch an application on the Shield TV.

<use_case> Launch streaming media apps (e.g. Netflix, YouTube, Plex) by friendly name. </use_case>

<important_notes>

  • Video output requires Onkyo AVR input set to 'strm-box' and TV input set to AVR HDMI port.

  • Confirms that the application is running in the foreground before returning.

  • Unknown app names suggest closest matches from configured apps. </important_notes>

Inputs: app (required). Returns: sent, detail, shield, outcome, +1 more

shield_list_appsList launchable appsA
Read-only

List the app names launch_app accepts (friendly name -> the link it opens).

<use_case> Discover valid app names for use with shield_launch_app. </use_case>

<important_notes>

  • Returns mapped friendly names from configuration. </important_notes>

Inputs: no named parameters. Returns: object

shield_rebootReboot the ShieldA
Destructive

Restart the Shield TV.

<use_case> Reboot the device when software is unresponsive or remotes require a cold reset. </use_case>

<important_notes>

  • Disruptive: stops active playback and disconnects network services.

  • Rate limited to 1 reboot per 120s to prevent rapid boot loops.

  • Requires ADB connection (mcp-server-shieldtv adb-setup). </important_notes>

Inputs: no named parameters. Returns: sent, advice, detail, outcome, +2 more

shield_send_keyPress a remote keyA

Press a remote-control key on the Shield, e.g. DPAD_DOWN with repeat=3 to move down three rows.

<use_case> Navigate Android TV interfaces, menus, and controls using directional pad, enter, back, and home. </use_case>

<important_notes>

  • Only sends allowed key enum values; power toggles and raw text typing are not supported. </important_notes>

Inputs: key (required), repeat. Returns: sent, detail, shield, outcome, +1 more

shield_set_powerWake or sleep the ShieldA
Idempotent

Wake the Shield ('on') or put it to sleep ('off').

<use_case> Manage device power state. </use_case>

<important_notes>

  • Uses discrete WAKEUP and SLEEP commands rather than ambiguous toggles.

  • Idempotent: returns 'unchanged' if already in requested state. </important_notes>

Inputs: state (required). Returns: sent, detail, shield, outcome, +1 more

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a distinct resource/action: app discovery vs launching, status vs now-playing vs remote diagnostics, power vs reboot vs key presses. There is no meaningful overlap that would cause misselection, and the descriptions clarify boundaries well.

    Naming Consistency5/5

    All tool names use a consistent snake_case shield_ prefix followed by a clear action, e.g. shield_list_apps, shield_get_status, shield_launch_app, shield_set_power. The pattern is predictable throughout the set.

    Tool Count5/5

    Eight tools is well-scoped for an Android TV/Shield controller: discovery, status, playback, remote diagnostics, power, launch, input, and reboot. Each tool earns its place without excess.

    Completeness4/5

    The set covers core lifecycle and control operations well, including discovery, status, playback metadata, launch, key input, power, and reboot. However, volume is reported by shield_get_status but there is no direct volume-setting tool, which is a minor but noticeable gap.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables controlling an Android device from an MCP client via ADB, including wireless debugging discovery, UI-tree inspection, and performing taps, swipes, typing, app actions, and shell commands without relying on screen coordinates.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables a macOS MCP client to control a real iPhone through CoreDevice services, including screenshots, normalized taps and swipes, text entry, hardware-button presses, and app launching or listing.
      11
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables control of a paired Android TV or Google TV through a relay: list devices, send remote keys, launch apps and intents, resolve and play titles via streaming providers, and observe the screen.
      63 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable assistants to operate an authorized Android device or emulator by locating structured controls, falling back to local OCR when needed, and running guarded navigation along observed paths.
      1
      MIT