AI agents

vivi-mcp is a small Model Context Protocol server (stdio) that lets Claude, Cursor and other MCP clients control a running Vivi over a local socket.

1. Enable remote control

Off by default. Turn on Settings → General → Remote control and restart Vivi, or run VIVI_IPC=1 vivi. The socket $XDG_RUNTIME_DIR/vivi.sock is private to your user (mode 0600); override it with VIVI_SOCKET.

2. Add it to your client

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and most others:

{
  "mcpServers": {
    "vivi": { "command": "vivi-mcp" }
  }
}

Claude Code: claude mcp add vivi -- vivi-mcp. VS Code: {"servers": {"vivi": {"type": "stdio", "command": "vivi-mcp"}}}. Flatpak: "command": "flatpak", "args": ["run", "--command=vivi-mcp", "io.github.loafer19.vivi"].

Tools

get_status, play, pause, toggle_pause, stop, seek, set_volume, open (file or URL), playlist_list, playlist_add, playlist_play, next, previous, search_library, set_subtitles, list_eq_presets, set_eq_preset; resources vivi://status and vivi://playlist.

Try it

VIVI_IPC=1 vivi &
npx @modelcontextprotocol/inspector vivi-mcp

Full reference and limitations: docs/mcp.md.