MCP - PipZ

"Open this YouTube tutorial in the top-right corner."
"화면 왼쪽에 띄워줘."
"Close the GitHub one and dim the rest to 60%."

How it works

Claude Desktop / Cursor / Cline (MCP client)
   └─ spawns: pipz-mcp (Node, over stdio)
       └─ shells out: pipz CLI
           └─ pipz:// URL scheme → PipZ.app opens / arranges / dims panels

No hosting, no cloud - the MCP server is a local Node process the client spawns on demand. It only talks to your locally-installed copy of PipZ.

Prerequisites

PipZ 1.2.0+ installed and activated. Earlier builds don't expose the full CLI surface.
The pipz CLI installed. Open PipZ → Settings → General → Automation → "Install Command Line Tool". This drops a binary at /usr/local/bin/pipz.
Node.js 20+, for npx.

Verify the CLI is wired up:

pipz --help

Install in your MCP client

Claude Desktop. Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pipz": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/ABSOLUTE/PATH/TO/pipz/Tools/pipz-mcp/src/index.ts"
      ]
    }
  }
}

Replace the path with the path to your local PipZ source checkout, then restart Claude Desktop. Cursor and Cline use the same command + args shape - point them at npx -y tsx <path>/Tools/pipz-mcp/src/index.ts.

Available tools

The server exposes eleven tools, one for each pipz CLI verb. The LLM picks which to call based on what the user asks.

Tool	What it does
`pipz_open`	Open a URL as a floating PiP. Optional placement (rect / preset slot) and content mode.
`pipz_list`	JSON snapshot of every open PiP - index, title, URL, frame, opacity, click-through state. The LLM calls this to resolve pronouns ("그 영상", "두 번째 거").
`pipz_close`	Close one PiP by 1-based index or by title substring.
`pipz_close_all`	Close every active PiP.
`pipz_arrange`	Snap every PiP to one screen edge (left / right / top / bottom).
`pipz_opacity`	Set opacity (0.2–1.0) on the active panel or all panels.
`pipz_move`	Move and resize a PiP to a specific x,y,w,h rect.
`pipz_preset_save`	Save the active PiP's frame to preset slot 1, 2, or 3.
`pipz_pip_active_tab`	PiP the user's current frontmost browser tab - no URL needed.
`pipz_clickthrough`	Toggle whether mouse clicks pass through a PiP to the app underneath.
`pipz_volume`	Set audio volume (0–100) of the video inside a PiP.

Sample prompts

"Open news.ycombinator.com as a floating window in the top-right corner."
"Float this YouTube video for me: https://youtu.be/dQw4w9WgXcQ"
"지금 보는 탭 화면에 띄워줘." (uses pipz_pip_active_tab - no URL needed)
"오른쪽으로 정렬해줘." (calls pipz_arrange with edge=right)
"60% 정도로 투명하게 만들어줘."
"두 번째 PiP 닫아줘." (the LLM calls pipz_list first, then pipz_close with index=2)
"이 위치 저장해 - 1번 슬롯에."
"클릭 통과시켜줘 - 뒤에 있는 창 작업해야 해."

Troubleshooting

pipz: command not found - the CLI isn't installed. Open PipZ → Settings → General → Automation → "Install Command Line Tool". The button only enables once you've activated your license.

Tool calls succeed but no window appears - confirm PipZ.app is running (it lives in the menu bar). The CLI launches it via the pipz:// URL scheme, which requires the app to be installed and the URL handler registered.