Google Search MCP Server

Instructions

Implementation Reference

• src/index.ts:246-281 (handler)

  The core handler function that performs the Google Custom Search API call for images, applies rate limiting, parses the response, and formats the results into a readable text output.
  async function performImageSearch(query: string, count: number = 5, start: number = 1) { checkRateLimit(); const url = new URL('https://www.googleapis.com/customsearch/v1'); url.searchParams.set('key', GOOGLE_API_KEY); url.searchParams.set('cx', GOOGLE_CSE_ID); url.searchParams.set('q', query); url.searchParams.set('num', Math.min(count, 10).toString()); url.searchParams.set('start', start.toString()); url.searchParams.set('searchType', 'image'); const response = await fetch(url, { headers: { 'Accept': 'application/json', } }); if (!response.ok) { throw new Error(`Google API error: ${response.status} ${response.statusText}\n${await response.text()}`); } const data = await response.json() as GoogleImageSearchResult; if (data.error) { throw new Error(`Google API error: ${data.error.code} ${data.error.message}`); } if (!data.items || data.items.length === 0) { return "No image results found for your query."; } // Format the image results return data.items.map((item, index) => `[${index + 1}] Title: ${item.title}\nDescription: ${item.snippet || 'No description'}\nImage URL: ${item.link}\n${item.image?.thumbnailLink ? `Thumbnail: ${item.image.thumbnailLink}` : ''}` ).join('\n\n'); }
• src/index.ts:45-72 (registration)

  Defines and registers the 'google_image_search' tool, including its name, description, and input schema for the MCP server.
  const IMAGE_SEARCH_TOOL: Tool = { name: "google_image_search", description: "Searches for images using Google's Custom Search API. " + "Best for finding images related to specific terms, concepts, or objects. " + "Returns image URLs, titles, and thumbnails. " + "Use this when needing to find relevant images or visual references.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Image search query" }, count: { type: "number", description: "Number of results (1-10, default 5)", default: 5 }, start: { type: "number", description: "Pagination start index (default 1)", default: 1 }, }, required: ["query"] } };
• src/index.ts:165-184 (schema)

  TypeScript interface defining the structure of the Google Image Search API response.
  interface GoogleImageSearchResult { kind: string; items?: Array<{ title: string; link: string; snippet: string; image?: { contextLink: string; height: number; width: number; thumbnailLink: string; thumbnailHeight: number; thumbnailWidth: number; }; }>; error?: { code: number; message: string; }; }
• src/index.ts:195-202 (schema)

  Type guard function for validating input arguments to the google_image_search tool.
  function isGoogleImageSearchArgs(args: unknown): args is { query: string; count?: number; start?: number } { return ( typeof args === "object" && args !== null && "query" in args && typeof (args as { query: string }).query === "string" ); }
• src/index.ts:309-319 (handler)

  Dispatch case in the main CallToolRequestHandler that validates args and calls the performImageSearch handler.
  case "google_image_search": { if (!isGoogleImageSearchArgs(args)) { throw new Error("Invalid arguments for google_image_search"); } const { query, count = 5, start = 1 } = args; const results = await performImageSearch(query, count, start); return { content: [{ type: "text", text: results }], isError: false, }; }