CiderMCP

Connect Cider (Apple Music client) to LLM clients over the Model Context Protocol. CiderMCP exposes Cider 4's scoped /api/v2 REST API as MCP tools, grouped so you can enable exactly what you want.

• 33 tools — 32 across 8 groups (playback, queue, library, audio, account, plugins, config, lyrics) plus a core status tool
• Tool groups map 1:1 to Cider's scoped API token permissions
• Auto-detection: with no group configuration, the server probes your token and enables exactly the scopes it has
• Built on MCP Python SDK v2 (MCPServer) and httpx2; stdio transport

Requirements

• Cider 4.0+ running with the RPC API enabled (Settings -> Connectivity -> Web API / RPC API)
• A Cider API token (Settings -> Connectivity -> Manage External Application Access to Cider)
• Python 3.13+ and uv

Install

Clone the repository, then point your MCP client at main.py:

{
  "mcpServers": {
    "cider": {
      "command": "uv",
      "args": ["--directory", "/Path/To/Cider3MCP", "run", "main.py"],
      "env": {
        "CIDER_HOST": "localhost",
        "CIDER_PORT": "10767",
        "CIDER_TOKEN": "YOUR_CIDER_API_TOKEN",
        "CIDER_TOOL_GROUPS": "playback,queue"
      }
    }
  }
}

CIDER_HOST and CIDER_PORT are optional (defaults localhost:10767). CIDER_TOKEN is required. CIDER_TOOL_GROUPS is optional — omit it to auto-detect. CIDER_TIMEOUT sets the HTTP timeout in seconds (default 10).

A cider-mcp console script is also available after uv sync.

Tool groups

CIDER_TOOL_GROUPS is a comma-separated, case-insensitive list. Unknown names are ignored with a warning; if nothing valid is provided, the server falls back to auto-detection.

Group	Cider permission (token scope)	Tools
playback	Playback Controls	7
queue	Up Next Queue	8
library	Your Music Library	8
audio	Sound Settings	2
account	Apple Music Sign-In	1
plugins	Plugin Management	1
config	App Settings	1
lyrics	Song Lyrics	4

When you create the token in Cider, tick the permissions for the groups you want. status_check reports which scopes the token actually has.

Auto-detection: when CIDER_TOOL_GROUPS is unset, the server probes each scope with read-only requests at startup and registers the granted groups. If Cider is not running at that moment, all groups are registered and calls return a clear "Cider is not reachable" error; restart the MCP server after Cider is up to refresh the registration.

Tools

Core (always enabled)

Tool	Description
status_check	Cider connectivity, client version, token validity, granted scopes, enabled groups

Playback (playback)

Tool	Description
playback_control	play / pause / toggle / stop / next / previous (with force for previous)
playback_seek	Seek to an absolute position in seconds
playback_status	State, position/duration, current track, audio quality
playback_mode	Get/set repeat (none/one/all), shuffle, autoplay
playback_speed	Get/set playback speed (0.25-4.0)
playback_play	Play by Apple Music type/id; pass shuffle to start an album/playlist
playback_play_url	Play an Apple Music share URL or API href (/v1/...)

Queue (queue)

Tool	Description
queue_get	Up-next queue with compact track info (raw items with detailed=true)
queue_add	Add an item next or later
queue_jump	Jump playback to a queue position
queue_move	Move a queue item between positions
queue_remove	Remove one or many items (lists apply in descending order)
queue_clear	Remove every item
queue_smart_optimizer	Get or set the Smart Queue Optimizer
queue_shuffle	Toggle shuffle

Library (library)

Tool	Description
library_list	Browse playlists, albums, artists, songs, recently-added; pass an id for children
library_now_playing	status / add / remove / love / dislike / rate / clear_rating
music_search	Apple Music catalog search
music_lookup	Apple Music catalog lookup by type/id
playlist_create	Create a playlist (optional seed tracks)
playlist_update	Update name/description/visibility
playlist_tracks	add / remove / replace / move tracks (writes are snapshotted by Cider)
playlist_history	Read playlist snapshots, or restore one by timestamp

Audio (audio)

Tool	Description
audio_get	Get one setting or all: volume, crossfade, automix, atmos, listening_mode, capture, normalization
audio_set	Set a setting (value for volume, mode for listening mode, enabled/params otherwise)

Lyrics (lyrics)

Tool	Description
lyrics_current	Lyrics for the current track
lyrics_get	Lyrics for a song id (optional provider)
lyrics_variations	List or fetch community lyric variations
lyrics_languages	Supported translation languages

Config (config)

Tool	Description
config_get	Read-only settings snapshot (credentials redacted), optional dot-path like audio.crossfade

Account (account)

Tool	Description
account_tokens	Storefront plus token-presence booleans. Token values are never returned

Plugins (plugins)

Tool	Description
plugin_install	Install a plugin from a .zip URL; Cider shows a consent dialog (may take up to 3 minutes)

Troubleshooting

Symptom	Cause / fix
UNAUTHORIZED_APP_TOKEN	Wrong or missing CIDER_TOKEN; create one under Settings -> Connectivity -> Manage External Application Access to Cider
INSUFFICIENT_SCOPE (names a scope)	The token was created without that permission; recreate it with the matching checkbox, or remove the group from CIDER_TOOL_GROUPS
CIDER_UNREACHABLE	Cider is not running, the RPC API is disabled, or host/port are wrong
Only status_check is listed	Auto-detection found no granted scopes (or CIDER_TOOL_GROUPS was invalid); check status_check output and your token permissions
Server logs appear in your MCP client	Expected: logs go to stderr; stdout is reserved for the MCP protocol

Use uv run main.py --list-tools to print the resolved groups and registered tool names.

Sources

• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk
• Cider API: https://cider.sh/docs/client/rpc and the scoped v2 API (GET /api/v2/events/catalog)

LLM Notice ⚠️

⚠️ New version of this tool, was completely rewritten by LLM in order to implement all the new features and improvements fast because I was lazy. ⚠️