Content
# MixCraft
Give Claude access to your music library. MixCraft is a hosted MCP server that connects Claude to Apple Music, letting Claude search your library, build playlists, and learn your taste over time.
**[mixcraft.app](https://mixcraft.app)** — set up in 60 seconds.
> **Spotify support**: Spotify's developer program restricts apps to a manually-managed allowlist that cannot be expanded for public distribution, so the hosted `mixcraft.app` deploy is Apple Music only. The full Spotify integration (adapter, OAuth, refresh logic) lives in this repo behind a single deploy-time flag — fork it, register your own Spotify dev app, and self-host for yourself and a few friends. See [docs/SELF-HOSTING.md](docs/SELF-HOSTING.md).
## Quick Start
### 1. Connect your music
Visit [mixcraft.app](https://mixcraft.app), sign in, and connect Apple Music. (Self-hosted forks with `enableSpotify` flipped on can also connect Spotify here.)
### 2. Add MixCraft to Claude
#### claude.ai / Desktop
**Connector (recommended for claude.ai)** — no API key needed:
1. Go to **Customize > Connectors > + > Add custom connector**
2. Fill in:
- **Name**: `Mixcraft`
- **Remote MCP server URL**: `https://mcp.mixcraft.app/mcp`
3. Expand **Advanced settings** and add:
- **OAuth Client ID**: `FLECRN3FqkNiXtGI`
4. Click **Add**, then sign in with your MixCraft account to authorize
Once connected, MixCraft appears in your connectors with all available tools:
**Plugin** — includes the playlist assistant skill for smarter curation:
1. Click the **+** button next to the prompt box and select **Plugins**
2. Select **Add plugin** to open the plugin browser
3. Find **MixCraft** and install it (choose **User**, **Project**, or **Local** scope)
If the marketplace isn't listed, add it first: run `/plugin`, go to the **Marketplaces** tab, and add `schuettc/mixcraft-app`.
Set your API key in your shell profile (`.bashrc`, `.zshrc`, etc.):
```bash
export MIXCRAFT_API_KEY="mx_your_key_here"
```
#### Claude Code CLI
**Plugin (recommended)** — includes the playlist assistant skill:
```
/plugin marketplace add schuettc/mixcraft-app
/plugin install mixcraft@mixcraft-app
/reload-plugins
```
Set your API key in your shell profile (`.bashrc`, `.zshrc`, etc.):
```bash
export MIXCRAFT_API_KEY="mx_your_key_here"
```
**MCP only** — tools without the playlist assistant skill:
Add to your project's `.mcp.json` (replace `mx_your_key_here` with your API key from [mixcraft.app](https://mixcraft.app)):
```json
{
"mcpServers": {
"mixcraft": {
"command": "npx",
"args": ["-y", "mixcraft-app@latest"],
"env": {
"MIXCRAFT_API_KEY": "mx_your_key_here"
}
}
}
}
```
#### Claude Desktop
Add to your config file (replace `mx_your_key_here` with your API key):
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"mixcraft": {
"command": "npx",
"args": ["-y", "mixcraft-app@latest"],
"env": {
"MIXCRAFT_API_KEY": "mx_your_key_here"
}
}
}
}
```
### 3. Use it
Just ask Claude about music:
- "Make me a playlist for a long drive"
- "What have I been listening to lately?"
- "Add some new songs to my workout playlist"
- "Find me something like Radiohead but more electronic"
- "I need focus music for coding"
## What You Get
### MCP Tools
Tools are registered based on which services you've connected. When both Apple Music and Spotify are connected, tools are prefixed (`apple_music_*`, `spotify_*`) so Claude knows which service to use.
**Shared tools** (available for both services):
| Tool | Description |
|------|-------------|
| `search_catalog` | Search songs, albums, and artists |
| `list_playlists` | List your library playlists |
| `get_playlist_tracks` | Get tracks in a playlist |
| `create_playlist` | Create a new playlist |
| `add_tracks` | Add tracks to a playlist |
| `get_recently_played` | Recent listening history |
| `get_library_songs` | Songs in your library |
| `add_to_library` | Add songs or albums to your library |
**Spotify-only tools** (registered only when Spotify is connected; requires a self-hosted deploy with `enableSpotify=true`):
| Tool | Description |
|------|-------------|
| `remove_playlist` | Remove (unfollow) a playlist |
| `remove_tracks_from_playlist` | Remove specific tracks from a playlist |
| `reorder_playlist_tracks` | Reorder tracks in a playlist |
| `update_playlist` | Rename, update description, or change visibility |
| `remove_from_library` | Remove songs or albums from your library |
| `get_top_items` | Your top artists or tracks by listening history |
### Playlist Assistant Skill
The plugin includes a skill that teaches Claude to be a thoughtful music companion:
- **Knows your taste** — checks your recently played and library before recommending anything
- **Curates intentionally** — builds playlists with energy arcs, genre bridges, and a mix of familiar favorites and new discoveries
- **Remembers preferences** — stores your likes, dislikes, and listening contexts in `.claude/mixcraft.local.md` so future sessions build on past ones
- **Service-aware** — knows the differences between Apple Music and Spotify (e.g., Apple Music playlists can't be deleted via API, Spotify's can) and adjusts behavior accordingly
## How It Works
MixCraft runs as a hosted service so you don't need to manage developer credentials or run any servers.
```
claude.ai <--HTTPS--> MixCraft API <--REST--> Apple Music / Spotify
Claude Code / Desktop <--stdio--> CLI (npx mixcraft-app) <--HTTPS--> MixCraft API
```
1. You connect your music service at [mixcraft.app](https://mixcraft.app) — Apple Music via MusicKit OAuth, Spotify via direct OAuth
2. Your music service tokens are encrypted with AWS KMS and stored in DynamoDB — MixCraft never sees or stores tokens in plaintext
3. **claude.ai** authenticates via OAuth 2.0 with PKCE — sign in once and the connector handles the rest
4. **Claude Code / Desktop** authenticate via API key — create one at [mixcraft.app](https://mixcraft.app) and set it as `MIXCRAFT_API_KEY`
5. When Claude calls a tool, the request hits the MixCraft API which decrypts your token, calls the appropriate music service, and returns the results
6. Spotify tokens are automatically refreshed when they expire — no re-authorization needed
For more details on security and data handling, see [SECURITY.md](docs/SECURITY.md).
## Self-hosting
Want Spotify support, or want to run the whole stack on your own AWS account? See [docs/SELF-HOSTING.md](docs/SELF-HOSTING.md) for the full walkthrough — Spotify dev app registration, allowlist management, secret seeding, and the single CDK context flag (`-c enableSpotify=true`) that turns it all on.
## License
MIT
