mixcloud-mcp-server

An MCP server for the Mixcloud API. Any MCP client can drive it: search and browse shows, follow/favorite/repost, and upload or edit your own shows — including scheduled publishing.

• Installation

• Client setup

• Configuration

• Authorization

• Tools

  • Read (no token)

  • Account actions (token)

  • Upload and edit (token)

  • OAuth

• Safety

Installation

uv tool install mixcloud-mcp-server

Check the installation:

mixcloud-mcp-server --print-config   # resolved paths and which credentials exist, no secrets
mixcloud-mcp-server --version

Related MCP server: SoundCloud MCP Server

Client setup

The server speaks stdio. The commands below use uvx, which runs the server straight from PyPI without a separate install.

Claude Code

claude mcp add mixcloud -- uvx mixcloud-mcp-server

Codex CLI

codex mcp add mixcloud -- uvx mixcloud-mcp-server

OpenCode

opencode mcp add mixcloud -- uvx mixcloud-mcp-server

Or manually in opencode.json:

{
    "mcp": {
        "servers": {
            "mixcloud": {
                "type": "local",
                "command": ["uvx", "mixcloud-mcp-server"]
            }
        }
    }
}

Pi

Pi reads MCP servers through the pi-mcp-adapter package:

pi install npm:pi-mcp-adapter
pi mcp add mixcloud -- uvx mixcloud-mcp-server

Use -l to write the entry into the project configuration instead of the user-level one. Pass the env file with --env MIXCLOUD_ENV_FILE=....

Hermes Agent

hermes mcp add mixcloud --command uvx --args mixcloud-mcp-server

In .hermes/config.yaml recommended to set Hermes Agent's env file:

mcp_servers:
    mixcloud:
        command: uvx
        args: ["mixcloud-mcp-server"]
        env:
            MIXCLOUD_ENV_FILE: "/home/you/.config/mixcloud-mcp-server/.env"

Then check with hermes mcp list.

Any other client

Run uvx mixcloud-mcp-server and pass MIXCLOUD_ENV_FILE in its environment.

Configuration

Authorization

Go to https://www.mixcloud.com/developers/create/ and create an app. You will get the CLIENT ID and CLIENT SECRET, write them in your .env.

Ask the agent:

1. auth_url() — returns a link to open in a browser

2. Open it, allow access, copy the code

3. exchange_code(code) — stores the token in the env file and never returns it

check_token() verifies the token; clear_token() forgets it locally. Mixcloud exposes no revoke endpoint.

Tools

Read (no token)

• search - Search shows, users, or tags by query; supports result type and pagination.

• get_object - Fetch a show, user, tag, or city by Mixcloud key or URL; optionally include metadata or authenticated fields.

• get_show - Fetch a show's key details, including its description, play and favorite counts, and tags.

• get_user - Fetch a user profile by key or URL.

• get_tag - Fetch a genre, city, or a genre combined with a city.

• list_connection - List an object's followers, following, favorites, shows, or listens; supports pagination and date filters.

• user_shows - List a user's shows with pagination and optional date filters.

• browse - List site-wide popular, hot, or new shows.

• genre_shows - List shows for a genre using one of the lists available for that tag.

• embed_html - Generate the HTML player embed for a show, with optional size and color.

• oembed - Get oEmbed data for a Mixcloud show URL.

Account actions (token)

• me - Fetch the authorized user's profile; optionally include metadata.

• follow_user - Follow a user, or unfollow them with undo=true.

• favorite_show - Favorite a show, or remove it from favorites with undo=true.

• repost_show - Repost a show, or remove the repost with undo=true.

• listen_later - Add a show to Listen Later, or remove it with undo=true.

Upload and edit (token)

• upload_show - Upload an audio show with optional artwork and metadata; files must be in MIXCLOUD_UPLOAD_DIR, and visibility defaults to unlisted.

• edit_show - Edit an uploaded show’s metadata, artwork, or visibility; tags, sections, and hosts are replaced wholesale when supplied.

OAuth

• auth_url - Generate the Mixcloud authorization URL; optionally specify a redirect URI.

• exchange_code - Exchange an OAuth code for an access token, then save the token locally without revealing it.

• check_token - Check whether the saved access token is valid and identify the authorized account.

• clear_token - Forget the access token locally; optionally remove it from the env file (does not revoke access on Mixcloud).

Objects are addressed by Mixcloud key: shows /username/show-name/, users /username/, tags /genres/funk/, cities /genres/city:athens/. Full URLs are accepted everywhere a key is.

Safety

• Uploads are sandboxed to MIXCLOUD_UPLOAD_DIR with an extension and size allowlist, so a prompt-injected path cannot exfiltrate arbitrary files from the machine.

• The access token is sent as a query parameter, so it is never logged and never included in error messages. Tools return a masked preview (...abcd) only.

• The client secret is read from the environment and never returned to the model.

• Redirects are not followed for authenticated calls, so a token cannot be replayed to another host.

• If you don't use some tools, it's recommended to turn them off in your agent.