Skip to main content
Glama
iplanwebsites

Image MCP Server

by iplanwebsites
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Remote

Image MCP Server

An MCP (Model Context Protocol) server that provides AI image generation capabilities using the ai-image npm module, which wraps around OpenAI and Replicate image inference APIs.

Features

  • generate_ai_image: Generate AI images with customizable prompts, sizes, models, and styles

  • square_image: Generate square images (1024x1024) - shortcut command

  • landscape_image: Generate landscape images (1536x1024) - shortcut command

  • portrait_image: Generate portrait images (1024x1536) - shortcut command

  • Built on the ai-image module for seamless integration with OpenAI and Replicate APIs

  • Simple setup and configuration

Related MCP server: GPT Image MCP Server

Installation

npm install -g image-mcp

Setup

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "image-mcp": {
      "command": "npx",
      "args": ["image-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "REPLICATE_API_TOKEN": "your-replicate-api-token",
        "MCP_TIMEOUT": "1200000"
      },
      "resetTimeoutOnProgress": true
    }
  }
}

Environment Variables

The server requires API keys for the underlying image generation services:

  • OPENAI_API_KEY: Your OpenAI API key for GPT-based models (we won't be supporting Dall-e models as they'll likely be dropped soon)

  • REPLICATE_API_TOKEN: Your Replicate API token for other AI models

Usage

Once configured, you can use the image generation functions through Claude:

generate_ai_image

Generate AI images with various parameters:

  • prompt (required): Text description of the image to generate

  • size (optional): Image dimensions in WIDTHxHEIGHT format (default: "1024x1024")

  • model (optional): Specific AI model to use

  • output (optional): Custom output file path

Shortcut Commands

For convenience, use these preset size commands:

  • square_image: Generate 1024x1024 square images

  • landscape_image: Generate 1536x1024 landscape images

  • portrait_image: Generate 1024x1536 portrait images

All shortcut commands accept the same parameters as generate_ai_image except size (which is preset).

Example prompts:

  • "A red cat in Picasso style"

  • "A sunset over mountains, photorealistic"

  • "Abstract geometric patterns in blue and gold"

Development

# Clone the repository
git clone https://github.com/iplanwebsites/image-mcp.git
cd image-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Start the server
npm start

Requirements

  • Node.js >= 18.0.0

  • Valid API keys for OpenAI and/or Replicate

TODOs

Urgent

  • Fix npm module issue: It only works locally...

Improvements

  • Better guides: Add more detailed setup guides with troubleshooting steps, an Add to cursor button, etc

  • Use ai-image library directly: Replace subprocess CLI calls with direct library imports

  • Return file paths: Return created image file paths in response

  • Local inference support: Add support for local models like Flux

  • Image optimization: Add lightweight image resizing and optimization options

  • Image captioning tool: Add captioning model for basic use cases (useful for models without vision)

License

MIT

Available Tools

5 tools
generate_ai_imageC

Generate AI images using the ai-image npm module

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe text prompt for image generation
sizeNoImage size in format WIDTHxHEIGHT (e.g., 1536x1024)1024x1024
modelNoAI model to use for generation (optional)
outputNoOutput file path (optional)
output_dirYesAbsolute path direcotry where to save the image (use current folder root by default)
qualityNoImage quality (low, medium, high, auto) - OpenAI onlyhigh
uselibincliNoUse library imports instead of CLI (default: false)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the implementation module ('ai-image npm module') but doesn't describe key behavioral traits such as whether this is a read-only or mutation operation, what permissions or authentication might be required, rate limits, error handling, or what the output looks like (e.g., file saved locally, URL returned). For a tool with 7 parameters and no annotations, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose and implementation method without any unnecessary words or structural issues. It's appropriately sized and front-loaded, with every part earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (7 parameters, no annotations, no output schema), the description is incomplete. It doesn't address behavioral aspects like mutation effects, authentication needs, or output format, and it lacks usage guidance relative to sibling tools. For a tool with this level of complexity and no structured support, the description should provide more context to be fully helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, meaning all parameters are documented in the schema itself. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain parameter interactions, default behaviors, or constraints not captured in schema descriptions). According to the rules, with high schema coverage (>80%), the baseline is 3 even with no param info in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Generate AI images') and specifies the implementation method ('using the ai-image npm module'), which provides a specific verb+resource combination. However, it doesn't distinguish this tool from its sibling tools (landscape_image, portrait_image, square_image), which likely serve similar image generation purposes but with different constraints or outputs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings or alternative approaches. It mentions the implementation module but doesn't explain the context, prerequisites, or exclusions for using this tool, leaving the agent with no usage direction beyond the basic function stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

landscape_imageA

Generate a landscape AI image (1536x1024) - works great for cover images - shortcut for generate_ai_image

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe text prompt for image generation
modelNoAI model to use for generation (optional)
outputNoOutput filename (optional), must end in .png
output_dirYesAbsolute path direcotry where to save the image (use current folder, or one that make sense for assets)
qualityNoImage quality (low, medium, high, auto) - OpenAI onlyhigh
uselibincliNoUse library imports instead of CLI (default: false)

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. While it mentions the tool generates images and works for cover images, it lacks critical behavioral details: whether this is a read-only or write operation, what permissions are needed, whether it makes external API calls, rate limits, or what happens on failure. For a generative AI tool with no annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with just two short sentences that pack essential information: tool function, dimensions, use case, and sibling relationship. Every word earns its place with zero waste, making it front-loaded and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of an AI image generation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., image file path, success status), error conditions, or behavioral constraints. While purpose and usage are clear, critical operational context is missing for a tool that likely involves external services and file system operations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds no parameter-specific information beyond what's in the schema. According to guidelines, when schema coverage is high (>80%), the baseline score is 3 even with no param info in the description, which applies here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verb ('Generate') and resource ('landscape AI image'), including exact dimensions (1536x1024) and use case ('works great for cover images'). It explicitly distinguishes from sibling 'generate_ai_image' by calling itself a 'shortcut' for that tool, providing clear differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance by stating this is a 'shortcut for generate_ai_image,' indicating when to use this tool versus its sibling. It also implies context with 'works great for cover images,' suggesting appropriate use cases. No misleading guidance is present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pizza-testC

Mock test tool that returns a password

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns a password, which implies it's a read operation, but doesn't clarify if this is a mock/dummy password, if it has security implications, or what the return format is. The 'mock test' hint suggests it's for testing, but this is insufficient for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that directly states the tool's function. It's front-loaded and wastes no words, though it could be slightly more informative. For a simple tool, this is appropriately concise and structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no annotations, no output schema, and a simple purpose, the description is incomplete. It doesn't explain what 'mock test' means, the nature of the returned password, or how this fits with sibling tools. For a tool that returns sensitive-sounding data (a password), more context is needed despite the low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, but that's acceptable here. Baseline is 4 for 0 parameters, as the schema fully covers the absence of inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Mock test tool that returns a password' states a purpose but is vague about what 'test' entails and doesn't specify the resource or context. It's not tautological (doesn't just restate 'pizza-test'), but it's too generic to be clear about the tool's specific function beyond returning a password.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings (e.g., image generation tools). It mentions it's a 'test' tool, which implies limited or debugging use, but doesn't explicitly state when or why an agent should choose it over alternatives, leaving usage unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

portrait_imageA

Generate a portrait AI image (1024x1536) - shortcut for generate_ai_image

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe text prompt for image generation
modelNoAI model to use for generation (optional)
outputNoOutput file path (optional)
output_dirYesAbsolute path direcotry where to save the image (use current folder root by default)
qualityNoImage quality (low, medium, high, auto) - OpenAI onlyhigh
uselibincliNoUse library imports instead of CLI (default: false)

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. While 'Generate' implies creation, it lacks critical behavioral details: it doesn't mention whether this is a read-only or destructive operation, what permissions are needed, rate limits, or what happens on failure. The description adds minimal behavioral context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with just two clauses, front-loading the core purpose and following with the sibling relationship. Every word earns its place with zero wasted text, making it highly efficient for agent comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is incomplete for a generative AI tool. It doesn't explain what the tool returns (e.g., image file, URL, metadata), error conditions, or behavioral constraints. While concise, it leaves significant gaps in understanding the tool's full operation and results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all 6 parameters. The description adds no parameter-specific information beyond implying portrait dimensions (1024x1536), which isn't directly tied to any parameter in the schema. Baseline 3 is appropriate when the schema does all the parameter documentation work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Generate'), resource ('portrait AI image'), and dimensions ('1024x1536'), distinguishing it from sibling tools like landscape_image and square_image by specifying portrait orientation. It also explicitly identifies it as a shortcut for generate_ai_image, providing clear differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('shortcut for generate_ai_image'), implying it should be used specifically for portrait images rather than the more general generate_ai_image or other sibling tools like landscape_image. This provides clear alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

square_imageA

Generate a square AI image (1024x1024) - shortcut for generate_ai_image

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe text prompt for image generation
modelNoAI model to use for generation (optional)
outputNoOutput file path (optional)
output_dirYesAbsolute path direcotry where to save the image (use current folder root by default)
qualityNoImage quality (low, medium, high, auto) - OpenAI onlyhigh
uselibincliNoUse library imports instead of CLI (default: false)

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. While it mentions the fixed 1024x1024 output size, it doesn't disclose important behavioral aspects like whether this is a read-only or write operation, potential rate limits, authentication requirements, or what happens when the image is generated (e.g., where it's saved, format, etc.). For a tool that presumably creates files, this is insufficient behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (one sentence) and front-loaded with the core purpose. Every word earns its place by specifying dimensions and providing the sibling tool comparison. No wasted words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description should do more to explain what this tool returns or produces. While it mentions the fixed square dimensions, it doesn't describe the output format, file location, or what happens after generation. For an image generation tool with 6 parameters, this leaves significant gaps in understanding the tool's complete behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. This meets the baseline expectation when schema coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Generate a square AI image') with precise dimensions (1024x1024) and explicitly distinguishes it from its sibling tool 'generate_ai_image' by calling it a 'shortcut'. This provides excellent differentiation and clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly positions this tool as a 'shortcut for generate_ai_image', providing clear guidance on when to use this tool versus its more general sibling. This direct comparison to an alternative tool is optimal for usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.0.13
    • First observedgenerate_ai_image
    • First observedlandscape_image
    • First observedpizza-test
    • First observedportrait_image
    • First observedsquare_image
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.9/5.0

Scored across 5 tools

Disambiguation2/5

Multiple tools have unclear boundaries and overlapping purposes. The 'landscape_image', 'portrait_image', and 'square_image' tools are explicitly described as shortcuts for 'generate_ai_image', creating significant ambiguity about when to use the general tool versus the specific ones. Additionally, 'pizza-test' appears unrelated to image generation, further confusing the tool set's purpose.

Naming Consistency3/5

The naming conventions are mixed but still readable. Most tools follow a consistent snake_case pattern (e.g., 'generate_ai_image', 'landscape_image'), but 'pizza-test' uses kebab-case, breaking the pattern. The verb styles are somewhat inconsistent, with 'generate' used for some and implied for others.

Tool Count4/5

The tool count of 5 is reasonable for an image generation server, though it feels slightly thin due to the redundancy among tools. It's not excessive, but the inclusion of a mock test tool ('pizza-test') that doesn't align with the domain reduces the effective scope, making the count borderline appropriate.

Completeness2/5

There are significant gaps in the tool surface for an image generation domain. The server lacks essential operations such as editing, resizing, filtering, or deleting images, and it offers no way to manage or retrieve generated images. The tools are narrowly focused on generation only, with redundant shortcuts, and the unrelated 'pizza-test' tool adds confusion rather than functionality.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches