Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:116-178 (handler)

  Core handler function that fetches screenshot from r.jina.ai API using POST request, extracts image URL, optionally downloads and resizes it to base64 JPEG using downloadImages helper, returns image or URL.
  async ({ url, firstScreenOnly, return_url }: { url: string; firstScreenOnly: boolean; return_url: boolean }) => { try { const props = getProps(); const headers: Record<string, string> = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Return-Format': firstScreenOnly === true ? 'screenshot' : 'pageshot', }; // Add Authorization header if bearer token is available if (props.bearerToken) { headers['Authorization'] = `Bearer ${props.bearerToken}`; } const response = await fetch('https://r.jina.ai/', { method: 'POST', headers, body: JSON.stringify({ url }), }); if (!response.ok) { return handleApiError(response, "Screenshot capture"); } const data = await response.json() as any; // Get the screenshot URL from the response const imageUrl = data.data.screenshotUrl || data.data.pageshotUrl; if (!imageUrl) { throw new Error("No screenshot URL received from API"); } // 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 the URL as text contentItems.push({ type: "text" as const, text: imageUrl, }); } else { // Download and process the image (resize to max 800px, convert to JPEG) const processedResults = await downloadImages(imageUrl, 1, 10000); const processedResult = processedResults[0]; if (!processedResult.success) { throw new Error(`Failed to process screenshot: ${processedResult.error}`); } contentItems.push({ type: "image" as const, data: processedResult.data!, mimeType: "image/jpeg", }); } return { content: contentItems, }; } catch (error) { return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`); }
• src/tools/jina-tools.ts:111-115 (schema)

  Zod input schema defining parameters for the tool: url (required URL), firstScreenOnly (boolean, default false for full page), return_url (boolean, default false for base64 image).
  { url: z.string().url().describe("The complete HTTP/HTTPS URL of the webpage to capture (e.g., 'https://example.com')"), firstScreenOnly: z.boolean().default(false).describe("Set to true for a single screen capture (faster), false for full page capture including content below the fold"), return_url: z.boolean().default(false).describe("Set to true to return screenshot URLs instead of downloading images as base64") },
• src/tools/jina-tools.ts:107-181 (registration)

  Registers the capture_screenshot_url tool on the MCP server using server.tool() if enabled by tool filtering.
  if (isToolEnabled("capture_screenshot_url")) { server.tool( "capture_screenshot_url", "Capture high-quality screenshots of web pages in base64 encoded JPEG format. Use this tool when you need to visually inspect a website, take a snapshot for analysis, or show users what a webpage looks like.", { url: z.string().url().describe("The complete HTTP/HTTPS URL of the webpage to capture (e.g., 'https://example.com')"), firstScreenOnly: z.boolean().default(false).describe("Set to true for a single screen capture (faster), false for full page capture including content below the fold"), return_url: z.boolean().default(false).describe("Set to true to return screenshot URLs instead of downloading images as base64") }, async ({ url, firstScreenOnly, return_url }: { url: string; firstScreenOnly: boolean; return_url: boolean }) => { try { const props = getProps(); const headers: Record<string, string> = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Return-Format': firstScreenOnly === true ? 'screenshot' : 'pageshot', }; // Add Authorization header if bearer token is available if (props.bearerToken) { headers['Authorization'] = `Bearer ${props.bearerToken}`; } const response = await fetch('https://r.jina.ai/', { method: 'POST', headers, body: JSON.stringify({ url }), }); if (!response.ok) { return handleApiError(response, "Screenshot capture"); } const data = await response.json() as any; // Get the screenshot URL from the response const imageUrl = data.data.screenshotUrl || data.data.pageshotUrl; if (!imageUrl) { throw new Error("No screenshot URL received from API"); } // 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 the URL as text contentItems.push({ type: "text" as const, text: imageUrl, }); } else { // Download and process the image (resize to max 800px, convert to JPEG) const processedResults = await downloadImages(imageUrl, 1, 10000); const processedResult = processedResults[0]; if (!processedResult.success) { throw new Error(`Failed to process screenshot: ${processedResult.error}`); } contentItems.push({ type: "image" as const, data: processedResult.data!, mimeType: "image/jpeg", }); } return { content: contentItems, }; } catch (error) { return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`); } }, ); }
• src/utils/image-downloader.ts:19-116 (helper)

  Helper utility called by the handler to download screenshot URL, resize using Cloudflare Workers image API (max 800px, JPEG 85% quality), encode to base64, with concurrency and timeout support.
  export async function downloadImages( urls: string | string[], concurrencyLimit: number = 3, timeoutMs: number = 15000 ): Promise<ProcessedImageResult[]> { // Normalize input to always be an array const urlArray = Array.isArray(urls) ? urls : [urls]; if (urlArray.length === 0) { return []; } const results: ProcessedImageResult[] = []; const queue = [...urlArray]; // Create a timeout promise const timeoutPromise = new Promise<ProcessedImageResult[]>((_, reject) => { setTimeout(() => reject(new Error('Download timeout')), timeoutMs); }); // Create the download promise const downloadPromise = (async () => { // Process images in batches while (queue.length > 0) { const batch = queue.splice(0, concurrencyLimit); const batchPromises = batch.map(async (url) => { try { // Skip SVG images as they can't be processed by Cloudflare image transformation if (url.toLowerCase().endsWith('.svg') || url.toLowerCase().includes('.svg?')) { return { url, success: false, mimeType: "image/jpeg", error: "SVG images are not supported for transformation" }; } // Use Cloudflare Workers image transformation // This automatically handles resizing and format conversion const response = await fetch(url, { cf: { image: { fit: 'scale-down', // Never enlarge, only shrink width: 800, // Max width height: 800, // Max height format: 'jpeg', // Convert to JPEG quality: 85, // Good quality with reasonable file size compression: 'fast' // Faster processing } } } as any); if (!response.ok) { return { url, success: false, mimeType: "image/jpeg", error: `HTTP ${response.status}: ${response.statusText}` }; } const arrayBuffer = await response.arrayBuffer(); const base64Image = Buffer.from(arrayBuffer).toString('base64'); return { url, success: true, data: base64Image, mimeType: "image/jpeg" }; } catch (error) { return { url, success: false, mimeType: "image/jpeg", error: error instanceof Error ? error.message : String(error) }; } }); const batchResults = await Promise.all(batchPromises); results.push(...batchResults); } return results; })(); // Race between download completion and timeout try { return await Promise.race([downloadPromise, timeoutPromise]); } catch (error) { if (error instanceof Error && error.message === 'Download timeout') { // Return what we have so far return results; } throw error; } }
• src/index.ts:100-102 (registration)

  Higher-level registration call to registerJinaTools which includes capture_screenshot_url among other tools, with tool filtering support.
  registerJinaTools(server, () => currentProps, enabledTools); return server;