Ideogram MCP Server

Instructions

Implementation Reference

• src/tools/generateImageHandler.ts:5-69 (handler)

  Main handler function for the 'generate_image' MCP tool. Validates input, constructs Ideogram API parameters, invokes the client, and formats the response with image URLs and file paths.
  export async function generateImageHandler(ideogramClient: IdeogramClient, args: any) { if (!args || typeof args.prompt !== "string") { throw new McpError( ErrorCode.InvalidParams, "Prompt is required and must be a string" ); } // 保存先ディレクトリとファイル名のデフォルト設定 const outputDir = typeof args.output_dir === "string" && args.output_dir.trim() !== "" ? args.output_dir : "docs"; const baseFilename = typeof args.base_filename === "string" && args.base_filename.trim() !== "" ? args.base_filename : "ideogram-image"; const params: IdeogramGenerateParams = { prompt: args.prompt, aspect_ratio: typeof args.aspect_ratio === "string" ? args.aspect_ratio : undefined, resolution: typeof args.resolution === "string" ? args.resolution : undefined, seed: typeof args.seed === "number" ? args.seed : undefined, magic_prompt: typeof args.magic_prompt === "string" && ["AUTO", "ON", "OFF"].includes(args.magic_prompt) ? args.magic_prompt as IdeogramGenerateParams["magic_prompt"] : undefined, rendering_speed: typeof args.rendering_speed === "string" && ["TURBO", "DEFAULT", "QUALITY"].includes(args.rendering_speed) ? args.rendering_speed as IdeogramGenerateParams["rendering_speed"] : undefined, style_codes: Array.isArray(args.style_codes) ? args.style_codes : undefined, style_type: typeof args.style_type === "string" ? args.style_type : undefined, negative_prompt: typeof args.negative_prompt === "string" ? args.negative_prompt : undefined, num_images: typeof args.num_images === "number" ? args.num_images : undefined, }; // Ideogram 3.0用のスタイルリファレンス機能 if (args.style_reference && typeof args.style_reference === "object") { const styleRef: IdeogramStyleReference = {}; const styleRefObj = args.style_reference as any; if (styleRefObj.urls && Array.isArray(styleRefObj.urls)) { styleRef.urls = styleRefObj.urls.slice(0, 3); } if (typeof styleRefObj.style_code === "string") { styleRef.style_code = styleRefObj.style_code; } if (typeof styleRefObj.random_style === "boolean") { styleRef.random_style = styleRefObj.random_style; } params.style_reference = styleRef; } // blur_maskオプション受け取り const blurMask = args.blur_mask === true; const response = await ideogramClient.generateImage(params, outputDir, baseFilename, blurMask); return { content: [ { type: "text", text: `Generated ${response.data.length} image(s):\n${response.data .map((img) => `URL: ${img.url}\nSaved to: ${(img.filepath ?? "").replace(/\\/g, "/")}`) .join("\n\n")}` } ] }; }
• src/tools/generateImageSchema.ts:1-98 (schema)

  Input schema (JSON Schema) defining parameters for the generate_image tool, including prompt, aspect_ratio, style options, etc.
  export const generateImageInputSchema = { type: "object", properties: { prompt: { type: "string", description: "The prompt to use for generating the image (must be in English)" }, aspect_ratio: { type: "string", description: "The aspect ratio for the generated image (see official docs for all 15 values)", enum: [ "1x1", "4x3", "3x4", "16x9", "9x16", "2x3", "3x2", "5x4", "4x5", "21x9", "9x21", "3x1", "1x3", "2x1", "1x2" ] }, resolution: { type: "string", description: "The resolution for the generated image (see official docs for all 69 values)", }, seed: { type: "integer", description: "Random seed. Set for reproducible generation.", minimum: 0, maximum: 2147483647 }, magic_prompt: { type: "string", description: "Whether to use magic prompt", enum: ["AUTO", "ON", "OFF"] }, rendering_speed: { type: "string", description: "Rendering speed for v3 (TURBO/DEFAULT/QUALITY)", enum: ["TURBO", "DEFAULT", "QUALITY"] }, style_codes: { type: "array", description: "Array of 8-char style codes", items: { type: "string" } }, style_type: { type: "string", description: "The style type for generation", enum: ["AUTO", "GENERAL", "REALISTIC", "DESIGN"] }, style_reference_images: { type: "array", description: "A set of images to use as style references (max 10MB, JPEG/PNG/WebP)", items: { type: "string", format: "binary" } }, negative_prompt: { type: "string", description: "Description of what to exclude from the image (must be in English)" }, num_images: { type: "number", description: "Number of images to generate (1-8)", minimum: 1, maximum: 8 }, style_reference: { type: "object", description: "Style reference options for Ideogram 3.0", properties: { urls: { type: "array", description: "URLs to reference images for style (max 3)", items: { type: "string" }, maxItems: 3 }, style_code: { type: "string", description: "Style code to apply (alternative to URLs)" }, random_style: { type: "boolean", description: "Whether to use a random style from Ideogram's library" } } }, output_dir: { type: "string", description: "Directory to save generated images (default: 'docs')." }, base_filename: { type: "string", description: "Base filename for saved images (default: 'ideogram-image'). Timestamp and image ID will be appended automatically." }, blur_mask: { type: "boolean", description: "Apply a blurred mask to the image edges (using a fixed mask image). If true, the output image will have blurred/feathered edges. (default: false)" } }, required: ["prompt"] };
• src/server.ts:28-38 (registration)

  Registers the 'generate_image' tool in the MCP ListTools response, providing name, description, and input schema.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "generate_image", description: "Generate an image using Ideogram AI", inputSchema: generateImageInputSchema } ] }; });
• src/server.ts:40-47 (registration)

  Dispatches MCP CallTool requests for 'generate_image' to the generateImageHandler function.
  server.setRequestHandler(CallToolRequestSchema, async (request) => { switch (request.params.name) { case "generate_image": return await generateImageHandler(ideogramClient, request.params.arguments); default: throw new McpError(ErrorCode.MethodNotFound, "Unknown tool"); } });
• src/ideogram-client.ts:27-147 (helper)

  Core IdeogramClient.generateImage method called by the handler; handles API call, image download, optional blurring, and local saving.
  async generateImage( params: IdeogramGenerateParams, outputDir?: string, baseFilename?: string, blurMask?: boolean ): Promise<IdeogramResponse> { // デフォルト値を補完（未指定なら 1x1） if (!params.aspect_ratio) { params.aspect_ratio = '1x1'; } // MagicPrompt 統合 & デフォルト AUTO if (params.magic_prompt_option && !params.magic_prompt) { params.magic_prompt = params.magic_prompt_option; delete (params as any).magic_prompt_option; } if (!params.magic_prompt) { params.magic_prompt = 'AUTO'; } // v3: rendering_speed を優先。model が指定されている場合は後方互換マッピング let rendering_speed: 'TURBO' | 'DEFAULT' | 'QUALITY' = params.rendering_speed ?? 'DEFAULT'; if (params.model) { switch (params.model) { case 'V_3_TURBO': case 'V_2_TURBO': case 'V_1_TURBO': rendering_speed = 'TURBO'; break; case 'V_3_QUALITY': rendering_speed = 'QUALITY'; break; // V_3, V_2, V_1 などは DEFAULT default: rendering_speed = 'DEFAULT'; } // API には model を送らない delete (params as any).model; } // request payload に rendering_speed を明示 (params as any).rendering_speed = rendering_speed; // クライアント内で model / rendering_speed の重複を排除 delete (params as any).model; delete (params as any).rendering_speed_option; // 念のため try { // 参照画像がURLとして提供されている場合 let formData: any = undefined; let requestConfig: any = { headers: { 'Api-Key': this.apiKey, 'Content-Type': 'application/json', }, }; // style_referenceでurlsが指定されている場合はマルチパートフォームデータを使用 if (params.style_reference?.urls && params.style_reference.urls.length > 0) { formData = new FormData(); // 参照画像をダウンロードしてFormDataに追加 for (let i = 0; i < params.style_reference.urls.length; i++) { const url = params.style_reference.urls[i]; try { const response = await axios.get(url, { responseType: 'arraybuffer' }); const buffer = Buffer.from(response.data, 'binary'); formData.append(`reference_image_${i+1}`, buffer, `reference_${i+1}.jpg`); } catch (error) { console.error(`Failed to download reference image from ${url}:`, error); } } // その他のパラメータをJSON文字列としてFormDataに追加 const paramsWithoutStyleReferenceUrls = { ...params, style_reference: { ...params.style_reference, urls: undefined // URLsを無効化して重複を避ける } }; formData.append('image_request', JSON.stringify(paramsWithoutStyleReferenceUrls)); // FormDataを使用するためのヘッダー設定 requestConfig.headers['Content-Type'] = 'multipart/form-data'; } // 通常のJSONリクエストまたはFormDataリクエストを送信 const response = await axios.post( `${this.baseUrl}/v1/ideogram-v3/generate`, formData || params, requestConfig ); // 画像を自動保存 const downloadPromises = response.data.data.map(async (img: { url: string; id: string }) => { const filepath = await downloadAndBlurMaskImage( img.url, img.id, outputDir, baseFilename, blurMask // 追加 ); return { ...img, filepath }; }); const updatedData = await Promise.all(downloadPromises); response.data.data = updatedData; const result: IdeogramResponse = { ...response.data, request: { ...params } }; return result; } catch (error) { if (axios.isAxiosError(error)) { const detail = typeof error.response?.data === 'string' ? error.response.data : JSON.stringify(error.response?.data, null, 2); throw new Error(`Ideogram API error (${error.response?.status}): ${detail || error.message}`); } throw error; } }