Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:562-631 (handler)

  Primary MCP tool handler for 'search_images': handles input args, calls executeImageSearch helper, optionally downloads and resizes images using downloadImages utility, formats response as MCP content (text metadata or image base64).

  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:554-561 (schema)

  Zod schema defining input parameters for search_images tool: query (required string), return_url (boolean default false), optional tbs/location/gl/hl for search refinement.

  {
  	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:550-633 (registration)

  Registration of 'search_images' tool in registerJinaTools function using McpServer.tool(), conditionally enabled via isToolEnabled check.

  if (isToolEnabled("search_images")) {
  	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.",
  		{
  			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")
  		},
  		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/utils/search.ts:269-300 (helper)

  Core helper function executeImageSearch: performs HTTP POST to svip.jina.ai image search endpoint (type='images'), handles errors, returns search results or error.

  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:34-41 (schema)

  TypeScript interface SearchImageArgs defining typed inputs for image search, imported into jina-tools.ts handler.

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