search_pixabay_images
Search for high-quality images on Pixabay using keywords, filters for image type and orientation, and customize the number of results per page.
Instructions
Search for images on Pixabay
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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) | |
| query | Yes | Search query terms |
Implementation Reference
- src/index.ts:385-450 (handler)Executes the search_pixabay_images tool by validating input arguments, making an API request to Pixabay for images based on query and filters, formatting the results with image URLs, and handling 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, including its name, description, and input schema.{ 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:282-310 (schema)Defines the input schema for the search_pixabay_images tool, specifying required 'query' and optional filters like image_type, orientation, and per_page with enums and constraints.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:126-157 (helper)Helper function to validate image search parameters (image_type, orientation, per_page) against Pixabay API allowed values and ranges.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 (query required, others optional).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');