search_images
Find openly-licensed images by entering search terms, filtering by license type, size, source, and more, helping users locate and use free, legal visuals efficiently.
Instructions
Search for openly-licensed images on Openverse
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| aspect_ratio | No | Image shape (tall, wide, square) | |
| creator | No | Filter by creator name | |
| extension | No | File type (jpg, png, gif, svg) | |
| license | No | License filter (e.g., by, by-sa, cc0) | |
| license_type | No | License type (commercial or modification) | |
| mature | No | Include mature content (default: false) | |
| page | No | Page number (default: 1) | |
| page_size | No | Results per page (default: 20, max: 500) | |
| query | Yes | Search terms (required) | |
| size | No | Image size (small, medium, large) | |
| source | No | Filter by source (e.g., flickr, wikimedia) |
Implementation Reference
- src/index.ts:51-87 (handler)The execute handler for the 'search_images' tool. It processes input arguments, builds query parameters for the Openverse API, makes a fetch request, and returns the JSON response or error.execute: async (args) => { const params: Record<string, string> = { q: args.query, page: String(args.page || 1), page_size: String(Math.min(args.page_size || DEFAULT_PAGE_SIZE, 500)), mature: String(args.mature || false) }; // Add optional parameters if (args.license) params.license = args.license; if (args.license_type) params.license_type = args.license_type; if (args.creator) params.creator = args.creator; if (args.source) params.source = args.source; if (args.extension) params.extension = args.extension; if (args.aspect_ratio) params.aspect_ratio = args.aspect_ratio; if (args.size) params.size = args.size; try { const queryParams = new URLSearchParams(params); const response = await fetch(`${OPENVERSE_API_BASE}/images/?${queryParams}`, { headers: { 'User-Agent': 'MCP-Openverse/1.0' } }); if (!response.ok) { throw new Error(`API request failed: ${response.status} ${response.statusText}`); } const data = await response.json(); return JSON.stringify(data, null, 2); } catch (error) { return JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error' }); } }
- src/index.ts:15-27 (schema)Zod schema defining the input parameters for the 'search_images' tool, including query and various optional filters.const searchImagesSchema = z.object({ query: z.string().describe('Search terms (required)'), page: z.number().optional().describe('Page number (default: 1)'), page_size: z.number().optional().describe('Results per page (default: 20, max: 500)'), license: z.string().optional().describe('License filter (e.g., by, by-sa, cc0)'), license_type: z.string().optional().describe('License type (commercial or modification)'), creator: z.string().optional().describe('Filter by creator name'), source: z.string().optional().describe('Filter by source (e.g., flickr, wikimedia)'), extension: z.string().optional().describe('File type (jpg, png, gif, svg)'), aspect_ratio: z.string().optional().describe('Image shape (tall, wide, square)'), size: z.string().optional().describe('Image size (small, medium, large)'), mature: z.boolean().optional().describe('Include mature content (default: false)') });
- src/index.ts:46-88 (registration)Registration of the 'search_images' tool using server.addTool(), specifying name, description, input schema, and inline execute handler.// Tool: search_images server.addTool({ name: 'search_images', description: 'Search for openly-licensed images on Openverse', parameters: searchImagesSchema, execute: async (args) => { const params: Record<string, string> = { q: args.query, page: String(args.page || 1), page_size: String(Math.min(args.page_size || DEFAULT_PAGE_SIZE, 500)), mature: String(args.mature || false) }; // Add optional parameters if (args.license) params.license = args.license; if (args.license_type) params.license_type = args.license_type; if (args.creator) params.creator = args.creator; if (args.source) params.source = args.source; if (args.extension) params.extension = args.extension; if (args.aspect_ratio) params.aspect_ratio = args.aspect_ratio; if (args.size) params.size = args.size; try { const queryParams = new URLSearchParams(params); const response = await fetch(`${OPENVERSE_API_BASE}/images/?${queryParams}`, { headers: { 'User-Agent': 'MCP-Openverse/1.0' } }); if (!response.ok) { throw new Error(`API request failed: ${response.status} ${response.statusText}`); } const data = await response.json(); return JSON.stringify(data, null, 2); } catch (error) { return JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error' }); } } });