Content
# Cider MCP Server
An [MCP](https://modelcontextprotocol.io) server that lets Claude control Apple Music playback through [Cider's](https://cider.sh) RPC API. Search the catalogue, start playback, manage your queue, and rate tracks — all from a conversation.
Built for use with [Claude Desktop](https://claude.ai/download) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
## Prerequisites
- **Node.js** 18+
- **[Cider](https://cider.sh)** (v2) running with RPC enabled
- An **app token** — configure in Cider under Settings → Connectivity → Manage External Application Access
## Setup
```bash
git clone https://github.com/thetokencarlos/cider-mcp-server.git
cd cider-mcp-server
npm install
cp .env.example .env
```
Open `.env` and paste your Cider app token:
```
CIDER_API_TOKEN=your-token-here
```
Build:
```bash
npm run build
```
## Register with Claude
### Claude Code
Add to your project or user settings (`claude mcp add`), or manually in `.claude/settings.json`:
```json
{
"mcpServers": {
"cider": {
"command": "node",
"args": ["/absolute/path/to/cider-mcp-server/dist/index.js"]
}
}
}
```
### Claude Desktop
Add to your config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"cider": {
"command": "node",
"args": ["/absolute/path/to/cider-mcp-server/dist/index.js"]
}
}
}
```
## Available Tools
| Tool | Description |
|------|-------------|
| `cider_status` | Current playback state — track, artist, album, position, volume, shuffle/repeat |
| `cider_search` | Search Apple Music for albums, songs, artists, or playlists |
| `cider_play` | Play content by Apple Music ID or URL |
| `cider_queue_add` | Add content to queue (play next or play later) |
| `cider_playback_control` | Play, pause, toggle, next, previous, stop |
| `cider_volume` | Get or set volume (0-1) |
| `cider_add_to_library` | Add currently playing to library |
| `cider_rate` | Rate current track (-1 dislike, 0 neutral, 1 love) |
| `cider_queue` | View the current playback queue |
## Example
```
You: What's playing right now?
Claude: [calls cider_status] Nothing is playing at the moment.
You: Search for "When Will We Land" by Barry Can't Swim
Claude: [calls cider_search] Found it — "When Will We Land?" (2023), 11 tracks.
You: Play that
Claude: [calls cider_play] Now playing.
```
## Architecture
- **`src/cider-client.ts`** — Typed HTTP client for Cider's RPC API. No MCP awareness.
- **`src/index.ts`** — MCP server with tool definitions wired to the client.
- Uses `@modelcontextprotocol/sdk` with stdio transport.
- Search uses Cider's Apple Music API passthrough (`/api/v1/amapi/run-v3`) and flattens the response into clean objects.
## License
MIT
