Skip to main content
clickwheel ships an optional Model Context Protocol server so AI clients like Claude Code, Claude Desktop, and the Claude apps can read and manage your library conversationally.

​
Install

That adds the clickwheel-mcp console script.

​
How it works

The server exposes tools across library (read), playlists, iPod, Plex, Apple Music, and Last.fm, each a thin RPC wrapper over the same actions.py core the CLI uses. See the generated MCP tool reference for the full list. A few behaviors worth knowing:
  • No auto-scan. Tool calls serve cached catalog data; run clickwheel scan in a terminal when you’ve added music.
  • Mutation tools advertise their risk. They carry the MCP destructiveHint annotation, which compatible clients can use to request approval. This is client behavior, not server-side authorization, so review the target and impact before allowing a mutation.
  • Logging goes to stderr (stdout is the wire protocol).

​
Connecting

​
Transports

  • clickwheel-mcp: stdio (the default), for local desktop clients.
  • clickwheel-mcp serve --http: Streamable HTTP, bound to localhost, intended to sit behind a tunnel for remote access.