mcp-gtv

MCP server for Google TV — control paired devices (keys, text, app launch) via @kud/gtv.

Features • Quick Start • MCP Client Setup • Tools Reference • Development

🌟 Features

• 🔌 Zero credentials — reads paired devices from ~/.config/gtv/config.json; no API key, no token, no extra setup

• 📺 Device switching — list all paired TVs and switch the active target at any time during a session

• 🎮 Full remote control — send any key from navigation and media to volume, power, and input

• ⌨️ IME text input — type arbitrary text into the focused field directly, without keycode mapping

• 🚀 App launcher — launch Netflix, YouTube, Prime Video, Spotify, and more by name, or pass any raw deep-link URI

• 🤖 Works everywhere — stdio transport is compatible with Claude Desktop, Claude Code, Cursor, and any MCP client

Related MCP server: AndroidTVMCP

🚀 Quick Start

1. Pair your TV first

Pairing is handled by the gtv CLI, not this server. If you have not paired yet:

npx @kud/gtv-cli pair

Follow the PIN prompt on the TV. The paired device is stored in ~/.config/gtv/config.json and shared automatically with this server.

2. Add the server to your MCP client

See MCP Client Setup below.

3. Ask Claude

Once the server is running, ask naturally:

"Turn up the volume on my TV" "Open Netflix" "Go back to the home screen" "Type 'Blade Runner' into the search field"

🔧 MCP Client Setup

The server uses stdio transport and requires no environment variables.

Claude Desktop / Claude Code

Add the following to your mcpServers configuration:

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

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json.

Claude Code — add to .mcp.json in your project root, or to ~/.claude/mcp.json for global availability.

Local development

{
  "mcpServers": {
    "mcp-gtv": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"]
    }
  }
}

Cursor / other MCP clients

Use the same npx -y @kud/mcp-gtv command with stdio transport. Consult your client's documentation for the exact config location.

🛠 Tools Reference

Valid keys for gtv_send_key

home  back  power  up  down  left  right  select
play  stop  next   prev  fwd  rwd
vol-up  vol-down  mute
menu  search  sleep  wakeup  input  enter
channel-up  channel-down  info  guide  settings

App catalogue for gtv_launch_app

You can also pass any raw deep-link URI directly (e.g. intent://...).

🔧 Development

Project layout

mcp-gtv/
├── src/
│   └── index.ts       # MCP server, all tool handlers
├── test/
│   └── tools.test.ts  # Unit tests (Node built-in test runner)
├── dist/              # Compiled output (tsup)
├── .mcp.json          # Local MCP client config for dev
└── tsup.config.ts

Scripts

Clone and run

git clone https://github.com/kud/mcp-gtv.git
cd mcp-gtv
npm install
npm run dev

Use npm run inspect to open the MCP Inspector and exercise the tools interactively without a full client.

Releasing

Releases are tag-driven via GitHub Actions with OIDC Trusted Publishers — no manual npm publish needed:

git tag v0.2.0
git push origin v0.2.0

🏗 Tech Stack

Ecosystem

@kud/androidtv-remote   ← low-level pairing & remote protocol
       ↑
  @kud/gtv              ← domain library (devices, keys, apps)
       ↑
  ┌────┴────┐
  │         │
mcp-gtv   gtv-cli       ← MCP surface / terminal surface

This server is the MCP client surface. @kud/gtv-cli is the interactive terminal counterpart — and the tool you use to pair devices before this server can control them.

MIT © kud — Made with ❤️