mcp-mpv-player

Instructions

Implementation Reference

• index.js:505-529 (handler)

  The implementation logic for the 'player_play' tool, which handles media playback via mpv and manages window focus for video files.

  case "player_play": {
    await ensureMpv();
    const flag = args.append ? "append-play" : "replace";
    await mpv("loadfile", [args.path, flag]);
  
    // If it's a video file, bring mpv window to foreground
    const VIDEO_EXTS = new Set([
      "mp4","mkv","avi","mov","wmv","flv","webm","m4v",
      "mpg","mpeg","ts","rmvb","3gp","ogv","hevc"
    ]);
    const ext = args.path.split(".").pop().toLowerCase().split("?")[0];
    if (VIDEO_EXTS.has(ext)) {
      // Wait for mpv to open the video window, then restore + focus
      await new Promise((r) => setTimeout(r, 800));
      await mpv("focus").catch(() => null);
      spawn("powershell", ["-NoProfile", "-NonInteractive", "-Command",
        "(New-Object -ComObject Shell.Application).Windows() | ForEach-Object { if ($_.FullName -like '*mpv*') { $_.Visible = $true } };" +
        "$wshell = New-Object -ComObject wscript.shell;" +
        "$wshell.AppActivate('mpv')"
      ], { detached: true, stdio: "ignore" }).unref();
    }
  
    await setProperty("pause", false);
    return ok(`Playing: ${args.path}`);
  }

• index.js:322-338 (registration)

  The tool definition (name, description, input schema) for 'player_play' in the TOOLS array.

  {
    name: "player_play",
    description:
      "Open and play a media file or URL. If mpv is not running, it will be launched automatically.",
    inputSchema: {
      type: "object",
      properties: {
        path: {
          type: "string",
          description: "Absolute file path or URL (http/https/rtmp etc.)",
        },
        append: {
          type: "boolean",
          description: "Append to current playlist instead of replacing it",
          default: false,
        },
      },