search
Pack: spotify · Endpoint: https://gateway.pipeworx.io/spotify/mcp
Search the Spotify catalog. type = comma-separated of album, artist, playlist, track, show, episode, audiobook. Returns matched items in named sections.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | string | yes | Search query |
type | string | no | Comma-separated types (default “track”) |
market | string | no | ISO 3166-1 alpha-2 market code (e.g., “US”) |
limit | number | no | 1-50 (default 20) |
offset | number | no | 0-1000 (default 0) |
Example call
Arguments
{
"query": "The Weeknd"
}curl
curl -X POST https://gateway.pipeworx.io/spotify/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"The Weeknd"}}}'TypeScript (@pipeworx/sdk)
import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();
const result = await pipeworx.call('search', {
"query": "The Weeknd"
});More examples
{
"query": "Blinding Lights",
"type": "track",
"market": "US",
"limit": 10
}Response shape
| Field | Type | Description |
|---|---|---|
tracks | object | |
albums | object | |
artists | object | |
playlists | object | |
shows | object | |
episodes | object | |
audiobooks | object |
Full JSON Schema
{
"type": "object",
"description": "Search results from Spotify catalog with named sections for each type",
"properties": {
"tracks": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "API endpoint for this section"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Track ID"
},
"name": {
"type": "string",
"description": "Track name"
},
"artists": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Artist ID"
},
"name": {
"type": "string",
"description": "Artist name"
}
}
}
},
"album": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Album ID"
},
"name": {
"type": "string",
"description": "Album name"
}
}
},
"duration_ms": {
"type": "number",
"description": "Duration in milliseconds"
},
"popularity": {
"type": "number",
"description": "Popularity 0-100"
},
"preview_url": {
"type": [
"string",
"null"
],
"description": "30s preview URL or null"
}
}
}
},
"limit": {
"type": "number",
"description": "Requested limit"
},
"offset": {
"type": "number",
"description": "Offset in results"
},
"total": {
"type": "number",
"description": "Total matching tracks"
}
}
},
"albums": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "API endpoint for this section"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Album ID"
},
"name": {
"type": "string",
"description": "Album name"
},
"artists": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Artist ID"
},
"name": {
"type": "string",
"description": "Artist name"
}
}
}
},
"release_date": {
"type": "string",
"description": "Release date (YYYY-MM-DD)"
},
"total_tracks": {
"type": "number",
"description": "Number of tracks"
}
}
}
},
"limit": {
"type": "number",
"description": "Requested limit"
},
"offset": {
"type": "number",
"description": "Offset in results"
},
"total": {
"type": "number",
"description": "Total matching albums"
}
}
},
"artists": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "API endpoint for this section"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Artist ID"
},
"name": {
"type": "string",
"description": "Artist name"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genre tags"
},
"popularity": {
"type": "number",
"description": "Popularity 0-100"
},
"followers": {
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "Total followers"
}
}
}
}
}
},
"limit": {
"type": "number",
"description": "Requested limit"
},
"offset": {
"type": "number",
"description": "Offset in results"
},
"total": {
"type": "number",
"description": "Total matching artists"
}
}
},
"playlists": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "API endpoint for this section"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Playlist ID"
},
"name": {
"type": "string",
"description": "Playlist name"
},
"owner": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"description": "Owner name"
}
}
},
"public": {
"type": "boolean",
"description": "Public status"
},
"tracks": {
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "Total tracks in playlist"
}
}
}
}
}
},
"limit": {
"type": "number",
"description": "Requested limit"
},
"offset": {
"type": "number",
"description": "Offset in results"
},
"total": {
"type": "number",
"description": "Total matching playlists"
}
}
},
"shows": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "API endpoint for this section"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Show ID"
},
"name": {
"type": "string",
"description": "Show name"
},
"publisher": {
"type": "string",
"description": "Publisher name"
},
"total_episodes": {
"type": "number",
"description": "Total episodes"
}
}
}
},
"limit": {
"type": "number",
"description": "Requested limit"
},
"offset": {
"type": "number",
"description": "Offset in results"
},
"total": {
"type": "number",
"description": "Total matching shows"
}
}
},
"episodes": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "API endpoint for this section"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Episode ID"
},
"name": {
"type": "string",
"description": "Episode name"
},
"release_date": {
"type": "string",
"description": "Release date"
},
"duration_ms": {
"type": "number",
"description": "Duration in milliseconds"
}
}
}
},
"limit": {
"type": "number",
"description": "Requested limit"
},
"offset": {
"type": "number",
"description": "Offset in results"
},
"total": {
"type": "number",
"description": "Total matching episodes"
}
}
},
"audiobooks": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "API endpoint for this section"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Audiobook ID"
},
"name": {
"type": "string",
"description": "Audiobook name"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Author name"
}
}
}
},
"total_chapters": {
"type": "number",
"description": "Total chapters"
}
}
}
},
"limit": {
"type": "number",
"description": "Requested limit"
},
"offset": {
"type": "number",
"description": "Offset in results"
},
"total": {
"type": "number",
"description": "Total matching audiobooks"
}
}
}
}
}Connect
Add this to your MCP client config, or use one-click install buttons:
{
"mcpServers": {
"spotify": {
"url": "https://gateway.pipeworx.io/spotify/mcp"
}
}
}See Getting Started for client-specific install steps.