Spotify Ads Agentic Tools
A Codex, Claude Code, and Gemini CLI plugin package that lets you manage Spotify advertising campaigns through natural language. Create campaigns, target audiences, launch ads, and pull performance reports — all by describing what you want in plain English.
Check out our post on the Spotify Engineering Blog.
Prerequisites
Install
Claude Code
claude plugin i spotify-ads-api
Codex
Add the Spotify Ads API plugin marketplace:
codex plugin marketplace add spotify/ads-agentic-tools
Restart Codex after adding the marketplace. Then open the plugin directory in the Codex app, or run codex and enter /plugins in the CLI. Select the added marketplace and install/enable Spotify Ads API.
Use codex plugin marketplace upgrade later to refresh installed marketplace sources.
Gemini CLI
gemini extensions install https://github.com/spotify/ads-agentic-tools
Restart Gemini CLI, then verify with /extensions. On Gemini, skills activate automatically from natural language (or browse them with /skills list); run /configure for first-time setup instead of /spotify-ads-api:configure. Note: automatic OAuth token refresh uses the macOS Keychain, so auto-refresh is macOS-only.
Install from source
Use a source checkout for local development or testing unreleased changes.
-
Clone the repository:
git clone https://github.com/spotify/ads-agentic-tools.git
cd ads-agentic-tools
-
For Codex, register the checkout as a local marketplace:
codex plugin marketplace add "$(pwd)"
Restart Codex after adding the marketplace. Then open the plugin directory in the Codex app, or run codex and enter /plugins in the CLI. Select the local marketplace and install/enable Spotify Ads API.
-
For Claude Code, launch with the plugin directory:
claude --plugin-dir "$(pwd)"
The Claude --plugin-dir flag loads the plugin for that session only. You can also add it to a shell alias if you use it frequently:
alias claude-ads='claude --plugin-dir /path/to/ads-agentic-tools'
-
For Gemini CLI, link the checkout as a local extension:
gemini extensions link "$(pwd)"
The link is a symlink, so source changes are picked up on the next Gemini CLI restart.
The repository includes platform-specific marketplace metadata: .agents/plugins/marketplace.json for Codex and .claude-plugin/marketplace.json for Claude Code. Gemini CLI has no marketplace file — it installs directly from the repository using the root gemini-extension.json manifest. Keep all three manifests in sync when changing plugin metadata.
Configure
-
Set up the redirect URI in Spotify Developer Dashboard:
- Go to developer.spotify.com and open your app settings
- Under Redirect URIs, add:
http://127.0.0.1:8080/callback
- Save the changes
- Open https://adsmanager.spotify.com/api-terms and make sure the ad account you want to use is selected. Accept the terms to authorize your client id to access your ad account through Ads API.
-
Configure OAuth credentials:
/spotify-ads-api:configure
(On Gemini CLI, run /configure instead — the skill names below all apply, but the slash-command prefix is Claude Code/Codex syntax.)
This opens your browser for Spotify authorization, then saves your tokens locally with automatic refresh.
-
Create your first campaign:
/spotify-ads-api:build-campaign Create an audio campaign called Summer Promo targeting US listeners aged 25-44 with $100/day budget
Authentication
The plugin supports three authentication modes:
OAuth 2.0 (Recommended)
Run /spotify-ads-api:configure or /spotify-ads-api:configure oauth. This launches an automated OAuth flow using a local Python script. Your tokens are stored locally and refresh automatically before API calls.
Manual OAuth
Run /spotify-ads-api:configure manual if Python is not available. You'll manually open the authorization URL, copy the redirect, and the plugin exchanges the code for tokens via curl.
Direct Token (Legacy)
Run /spotify-ads-api:configure token <your-token>. Accepts a pre-obtained access token. No automatic refresh — token expires in ~1 hour.
Available Skills
