search
Find tracks, albums, artists, or playlists in Spotify's music catalog using specific search queries and filters.
Instructions
Search for tracks, albums, artists, or playlists
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>",
"type": "<type>"
},
"name": "search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| type | Yes | Type of item to search for | |
| limit | No | Maximum number of results (1-50) |
Implementation Reference
- src/handlers/search.ts:5-26 (handler)The SearchHandler class provides the core implementation of the 'search' tool, handling input validation and making an API request to Spotify's search endpoint.
export class SearchHandler { constructor(private api: SpotifyApi) {} async search(args: SearchArgs) { const { query, type, limit = 20 } = args; if (limit < 1 || limit > 50) { throw new McpError( ErrorCode.InvalidParams, 'Limit must be between 1 and 50' ); } const params = { q: encodeURIComponent(query), type, limit }; return this.api.makeRequest(`/search${this.api.buildQueryString(params)}`); } } - src/types/search.ts:1-40 (schema)TypeScript interfaces defining the input (SearchArgs) and output (SearchResponse) structures for the 'search' tool.
export interface SearchArgs { query: string; type: 'track' | 'album' | 'artist' | 'playlist'; limit?: number; } export interface SearchResponse { tracks?: { items: any[]; limit: number; next: string | null; offset: number; previous: string | null; total: number; }; albums?: { items: any[]; limit: number; next: string | null; offset: number; previous: string | null; total: number; }; artists?: { items: any[]; limit: number; next: string | null; offset: number; previous: string | null; total: number; }; playlists?: { items: any[]; limit: number; next: string | null; offset: number; previous: string | null; total: number; }; } - src/index.ts:116-140 (registration)Registration of the 'search' tool in the ListTools response, including name, description, and input schema.
name: 'search', description: 'Search for tracks, albums, artists, or playlists', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query' }, type: { type: 'string', description: 'Type of item to search for', enum: ['track', 'album', 'artist', 'playlist'] }, limit: { type: 'number', description: 'Maximum number of results (1-50)', minimum: 1, maximum: 50, default: 20 } }, required: ['query', 'type'] }, }, - src/index.ts:702-708 (registration)Handler for CallTool requests named 'search', which validates arguments and delegates to SearchHandler.search().
case 'search': { const args = this.validateArgs<SearchArgsType>(request.params.arguments, ['query', 'type']); const result = await this.searchHandler.search(args); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; } - src/index.ts:87-87 (registration)Instantiation of the SearchHandler instance used by the MCP server.
this.searchHandler = new SearchHandler(this.api);