search_pixabay_images
Search for free images on Pixabay using keywords, filter by type and orientation, and get results with URLs and metadata.
Instructions
Search for images on Pixabay
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query terms | |
| image_type | No | Filter results by image type | all |
| orientation | No | Filter results by image orientation | all |
| per_page | No | Number of results per page (3-200) |
Implementation Reference
- src/index.ts:385-450 (handler)Executes the 'search_pixabay_images' tool: validates input, calls Pixabay image search API with parameters, formats results as text list with URLs, handles no results and errors gracefully.if (request.params.name === 'search_pixabay_images') { if (!isValidSearchArgs(request.params.arguments)) { throw new McpError( ErrorCode.InvalidParams, 'Invalid search arguments. "query" (string) is required.' ); } assertValidImageSearchParams(request.params.arguments); const { query, image_type = 'all', orientation = 'all', per_page = 20 } = request.params.arguments; try { const response = await axios.get<PixabayResponse>(PIXABAY_API_URL, { params: { key: API_KEY, q: query, image_type: image_type, orientation: orientation, per_page: per_page, safesearch: true // Enable safe search by default }, }); if (response.data.hits.length === 0) { return { content: [{ type: "text", text: `No images found for query: "${query}"` }] }; } // Format the results const resultsText = response.data.hits.map((hit: PixabayImage) => `- ${hit.tags} (User: ${hit.user}): ${hit.webformatURL}` ).join('\n'); return { content: [{ type: "text", text: `Found ${response.data.totalHits} images for "${query}":\n${resultsText}` }] }; } catch (error: unknown) { let errorMessage = 'Failed to fetch images from Pixabay.'; if (axios.isAxiosError(error)) { errorMessage = `Pixabay API error: ${error.response?.status} ${error.response?.data?.message || error.message}`; // Pixabay might return 400 for invalid key, but doesn't give a clear message if (error.response?.status === 400) { errorMessage += '. Please check if the API key is valid.'; } } else if (error instanceof Error) { errorMessage = error.message; } logPixabayError('image', error); return { content: [{ type: "text", text: errorMessage }], isError: true }; } }
- src/index.ts:279-311 (registration)Registers the 'search_pixabay_images' tool in the MCP server's listTools handler, providing name, description, and detailed input schema with validation rules.{ name: "search_pixabay_images", description: "Search for images on Pixabay", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query terms" }, image_type: { type: "string", enum: ["all", "photo", "illustration", "vector"], description: "Filter results by image type", default: "all" }, orientation: { type: "string", enum: ["all", "horizontal", "vertical"], description: "Filter results by image orientation", default: "all" }, per_page: { type: "number", description: "Number of results per page (3-200)", default: 20, minimum: 3, maximum: 200 } }, required: ["query"] } },
- src/index.ts:24-36 (schema)TypeScript interface defining the structure of Pixabay image objects returned by the API, used for typing the response in the handler.interface PixabayImage { id: number; pageURL: string; type: string; tags: string; previewURL: string; webformatURL: string; largeImageURL: string; views: number; downloads: number; likes: number; user: string; }
- src/index.ts:126-157 (helper)Helper function to validate image_type, orientation, and per_page parameters against Pixabay API constraints, throwing MCP errors for invalid values.function assertValidImageSearchParams(args: { image_type?: string; orientation?: string; per_page?: number }): void { const { image_type, orientation, per_page } = args; if (image_type !== undefined && !IMAGE_TYPE_OPTIONS.includes(image_type)) { throw new McpError( ErrorCode.InvalidParams, `image_type 必须是 ${IMAGE_TYPE_OPTIONS.join(', ')} 之一。` ); } if (orientation !== undefined && !ORIENTATION_OPTIONS.includes(orientation)) { throw new McpError( ErrorCode.InvalidParams, `orientation 必须是 ${ORIENTATION_OPTIONS.join(', ')} 之一。` ); } if (per_page !== undefined) { if (!Number.isInteger(per_page)) { throw new McpError( ErrorCode.InvalidParams, 'per_page 必须是整数。' ); } if (per_page < MIN_PER_PAGE || per_page > MAX_PER_PAGE) { throw new McpError( ErrorCode.InvalidParams, `per_page 需在 ${MIN_PER_PAGE}-${MAX_PER_PAGE} 范围内。` ); } } }
- src/index.ts:98-106 (helper)Type guard helper to check if tool arguments match the expected shape for image search (requires 'query' string, optional typed others).const isValidSearchArgs = ( args: any ): args is { query: string; image_type?: string; orientation?: string; per_page?: number } => typeof args === 'object' && args !== null && typeof args.query === 'string' && (args.image_type === undefined || typeof args.image_type === 'string') && (args.orientation === undefined || typeof args.orientation === 'string') && (args.per_page === undefined || typeof args.per_page === 'number');