# SoundCloud MCP

[![PyPI version](https://img.shields.io/pypi/v/soundcloud-mcp.svg)](https://pypi.org/project/soundcloud-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

MCP server for uploading and managing tracks on **SoundCloud** using the [official API](https://developers.soundcloud.com/docs/api/guide.html).

Use it from Cursor or Claude Desktop to upload MP3s, update metadata, and manage your catalog — pairs naturally with [suno-mcp](https://github.com/David-J-Shibley/suno-mcp) for generate → upload workflows.

## Features

- **Official SoundCloud API** — OAuth 2.1 + PKCE, no browser scraping for uploads
- **Upload tracks** — MP3, WAV, FLAC with title, description, tags, artwork
- **Manage library** — list, get, update, delete tracks
- **Token refresh** — automatic OAuth token renewal

## Requirements

- Python 3.10+
- SoundCloud **Artist Pro** account
- A registered SoundCloud API app ([soundcloud.com/you/apps](https://soundcloud.com/you/apps))

## Register your SoundCloud app

| Field | What to enter |
|-------|---------------|
| **App name** | `SoundCloud MCP` (or anything descriptive) |
| **Description** | `Personal MCP server for uploading AI-generated music to my SoundCloud account` |
| **Website** | `https://github.com/David-J-Shibley/soundcloud-mcp` *(optional)* |
| **Redirect URI** | `http://127.0.0.1:8765/callback` *(must match exactly)* |

The **Website** field is optional — it is **not** used for OAuth. The **Redirect URI** must match character-for-character.

## Quick Start

### Install from PyPI

```bash
pip install soundcloud-mcp
cp .env.example .env
# Edit .env with client_id and client_secret from soundcloud.com/you/apps
soundcloud-mcp-auth
```

### Install from source

```bash
git clone https://github.com/David-J-Shibley/soundcloud-mcp.git
cd soundcloud-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
```

### Authenticate (one time)

```bash
soundcloud-mcp-auth
```

Tokens are saved to `~/.soundcloud-mcp/tokens.json`.

If the browser page is blank/white, your redirect URI doesn't match — see [Troubleshooting](#troubleshooting).

## Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "soundcloud": {
      "command": "/absolute/path/to/soundcloud-mcp/.venv/bin/python",
      "args": ["-m", "soundcloud_mcp"],
      "cwd": "/absolute/path/to/soundcloud-mcp",
      "env": {
        "DYLD_LIBRARY_PATH": "/opt/homebrew/opt/expat/lib"
      }
    }
  }
}
```

Put credentials in `.env` in the project directory (recommended) — `cwd` lets the server load them automatically.

## Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "soundcloud": {
      "command": "/absolute/path/to/soundcloud-mcp/.venv/bin/python",
      "args": ["-m", "soundcloud_mcp"],
      "cwd": "/absolute/path/to/soundcloud-mcp"
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `soundcloud_get_me` | Your SoundCloud profile |
| `soundcloud_list_my_tracks` | List your uploaded tracks |
| `soundcloud_get_track` | Track details by ID |
| `soundcloud_upload_track` | Upload MP3/WAV/FLAC with metadata |
| `soundcloud_update_track` | Edit title, description, tags, artwork |
| `soundcloud_delete_track` | Remove a track |

## Example workflow (Suno → SoundCloud)

1. Generate a song with **suno-mcp**
2. Download the MP3 with `suno_download_song`
3. Upload with **soundcloud-mcp**:

```
Upload ~/Downloads/suno/my-song.mp3 to SoundCloud as "My New Track" with tags "electronic ai-generated"
```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `SOUNDCLOUD_CLIENT_ID` | — | From soundcloud.com/you/apps |
| `SOUNDCLOUD_CLIENT_SECRET` | — | From soundcloud.com/you/apps |
| `SOUNDCLOUD_REDIRECT_URI` | `http://127.0.0.1:8765/callback` | Must match app settings |
| `SOUNDCLOUD_TOKEN_FILE` | `~/.soundcloud-mcp/tokens.json` | OAuth token storage |

## Troubleshooting

**Blank/white OAuth page** — Redirect URI mismatch. In [soundcloud.com/you/apps](https://soundcloud.com/you/apps), set exactly:

```
http://127.0.0.1:8765/callback
```

Use `127.0.0.1` not `localhost`, `http://` not `https://`, no trailing slash.

**Not authenticated** — Run `soundcloud-mcp-auth` again.

**Manual login** — `soundcloud-mcp-auth --no-browser` prints the URL to paste into your browser.

## Disclaimer

Unofficial project, not affiliated with SoundCloud. Use in accordance with [SoundCloud's API Terms of Use](https://developers.soundcloud.com/docs/api/terms-of-use).

## Contributing

Issues and pull requests welcome on [GitHub](https://github.com/David-J-Shibley/soundcloud-mcp).

See [PUBLISHING.md](PUBLISHING.md) for PyPI release instructions.

## License

MIT — see [LICENSE](LICENSE).