Skip to main content

Documentation Index

Fetch the complete documentation index at: https://clickwheel.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

pipx inject clickwheel 'clickwheel[mcp]'
That adds the clickwheel-mcp console script.

​
How it works

The server exposes ~37 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.
  • Destructive tools are gated by the client. Mutating tools carry the MCP destructiveHint annotation, so compliant clients show an Allow/Deny prompt before they run.
  • Logging goes to stderr (stdout is the wire protocol).

​
Connecting

Claude Code: 
claude mcp add clickwheel clickwheel-mcp --scope user
Claude Desktop — add to claude_desktop_config.json: 
{ "mcpServers": { "clickwheel": { "command": "clickwheel-mcp" } } }
From your phone (the Claude app): the server can run over Streamable HTTP behind a Cloudflare Tunnel, so you can reach it remotely. See Remote / mobile access.

​
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.