> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickwheel.fm/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Drive clickwheel from Claude and other MCP clients.

clickwheel ships an optional [Model Context Protocol](https://modelcontextprotocol.io)
server so AI clients like Claude Code, Claude Desktop, and the Claude apps can
read and manage your library conversationally.

## Install

```bash theme={null}
pipx inject clickwheel 'clickwheel[mcp]'
```

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](/reference/mcp-tools) 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 (Claude Code, Claude
  Desktop, claude.ai) show an Allow/Deny prompt before they run. Nothing changes
  without your confirmation.
* **Logging goes to stderr** (stdout is the wire protocol).

## Connecting

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add clickwheel clickwheel-mcp --scope user
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "clickwheel": { "command": "clickwheel-mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="Mobile / claude.ai">
    The server can run over Streamable HTTP behind a Cloudflare Tunnel, so the
    Claude apps (including your phone) can reach it remotely. See
    [Remote / mobile access](/guides/remote-mcp).
  </Tab>
</Tabs>

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