Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:330-398 (handler)

  Primary MCP tool handler for 'search_images'. Handles input validation (via schema), token check, executes core search, optionally downloads/resizes images from results, and formats MCP content blocks with images or metadata.

  async ({ query, return_url, tbs, location, gl, hl }: SearchImageArgs) => {
  	try {
  		const props = getProps();
  
  		const tokenError = checkBearerToken(props.bearerToken);
  		if (tokenError) {
  			return tokenError;
  		}
  
  		const searchResult = await executeImageSearch({ query, return_url, tbs, location, gl, hl }, props.bearerToken);
  
  		if ('error' in searchResult) {
  			return createErrorResponse(searchResult.error);
  		}
  
  		const data = { results: searchResult.results };
  
  		// Prepare response content - always return as list structure for consistency
  		const contentItems: Array<{ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }> = [];
  
  		if (return_url) {
  			// Return each result as individual text items
  			if (data.results && Array.isArray(data.results)) {
  				for (const result of data.results) {
  					contentItems.push({
  						type: "text" as const,
  						text: yamlStringify(result),
  					});
  				}
  			}
  		} else {
  			// Extract image URLs from search results
  			const imageUrls: string[] = [];
  			if (data.results && Array.isArray(data.results)) {
  				for (const result of data.results) {
  					if (result.imageUrl) {
  						imageUrls.push(result.imageUrl);
  					}
  				}
  			}
  
  			if (imageUrls.length === 0) {
  				throw new Error("No image URLs found in search results");
  			}
  
  			// Download and process images (resize to max 800px, convert to JPEG)
  			// 15 second timeout - returns partial results if timeout occurs
  			const downloadResults = await downloadImages(imageUrls, 3, 15000);
  
  			// Add successful downloads as images
  			for (const result of downloadResults) {
  				if (result.success && result.data) {
  					contentItems.push({
  						type: "image" as const,
  						data: result.data,
  						mimeType: result.mimeType,
  					});
  				}
  			}
  
  
  		}
  
  		return {
  			content: contentItems,
  		};
  	} catch (error) {
  		return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`);
  	}

• src/tools/jina-tools.ts:322-329 (schema)

  Zod input schema for search_images tool, defining parameters like query, return_url, time/location filters.

  {
  	query: z.string().describe("Image search terms describing what you want to find (e.g., 'sunset over mountains', 'vintage car illustration', 'data visualization chart')"),
  	return_url: z.boolean().default(false).describe("Set to true to return image URLs, title, shapes, and other metadata. By default, images are downloaded as base64 and returned as rendered images."),
  	tbs: z.string().optional().describe("Time-based search parameter, e.g., 'qdr:h' for past hour, can be qdr:h, qdr:d, qdr:w, qdr:m, qdr:y"),
  	location: z.string().optional().describe("Location for search results, e.g., 'London', 'New York', 'Tokyo'"),
  	gl: z.string().optional().describe("Country code, e.g., 'dz' for Algeria"),
  	hl: z.string().optional().describe("Language code, e.g., 'zh-cn' for Simplified Chinese")
  },

• src/tools/jina-tools.ts:318-321 (registration)

  MCP server registration of the 'search_images' tool via server.tool(), including name, description, schema reference, and handler function.

  // Search Images tool - search for images on the web using Jina Search API
  server.tool(
  	"search_images",
  	"Search for images across the web, similar to Google Images. Use this when you need to find photos, illustrations, diagrams, charts, logos, or any visual content. Perfect for finding images to illustrate concepts, locating specific pictures, or discovering visual resources. Images are returned by default as small base64-encoded JPEG images.",

• src/utils/search.ts:125-156 (helper)

  Core helper function executing the Jina AI image search API call, handling request params, error cases, and returning raw search results.

  export async function executeImageSearch(
      searchArgs: SearchImageArgs,
      bearerToken: string
  ): Promise<SearchResultOrError> {
      try {
          const response = await fetch('https://svip.jina.ai/', {
              method: 'POST',
              headers: {
                  'Accept': 'application/json',
                  'Content-Type': 'application/json',
                  'Authorization': `Bearer ${bearerToken}`,
              },
              body: JSON.stringify({
                  q: searchArgs.query,
                  type: 'images',
                  ...(searchArgs.tbs && { tbs: searchArgs.tbs }),
                  ...(searchArgs.location && { location: searchArgs.location }),
                  ...(searchArgs.gl && { gl: searchArgs.gl }),
                  ...(searchArgs.hl && { hl: searchArgs.hl })
              }),
          });
  
          if (!response.ok) {
              return { error: `Image search failed for query "${searchArgs.query}": ${response.statusText}` };
          }
  
          const data = await response.json() as any;
          return { query: searchArgs.query, results: data.results || [] };
      } catch (error) {
          return { error: `Image search failed for query "${searchArgs.query}": ${error instanceof Error ? error.message : String(error)}` };
      }
  }

• src/utils/search.ts:22-29 (schema)

  TypeScript interface defining input arguments for image search, used by handler and helpers.

  export interface SearchImageArgs {
      query: string;
      return_url?: boolean;
      tbs?: string;
      location?: string;
      gl?: string;
      hl?: string;
  }