imagine-mcp

MCP server for AI image generation and manipulation. Currently supports stock image search via Unsplash. and local image reading from file path, URL, or data URI.

Features

Stock Image Search (Unsplash)

• Search for high-quality stock photos from Unsplash
• Filter by orientation (landscape, portrait, squarish)
• Filter by color
• Pagination support
• Returns image URLs in multiple sizes (full, regular, small, thumbnail)
• Includes photographer attribution and links

Image Reader

• Read raw image bytes from local file paths, HTTP(S) URLs, or data URIs
• Returns source metadata (source, sourceType, mimeType, sizeBytes, sha256)
• Optionally returns base64 in the tool response

Prerequisites

Unsplash API Key

You need an Unsplash API access key to use the stock image search feature. The read-image tool works without any upload or provider credentials.

1. Sign up at Unsplash Developers
2. Create a new application
3. Copy your Access Key
4. Set the environment variable: export UNSPLASH_ACCESS_KEY=your_access_key_here

Installation

pnpm install

Development

# Set your Unsplash API key
export UNSPLASH_ACCESS_KEY=your_access_key_here

# Run in development mode (stdio transport)
pnpm dev

# Run with HTTP transport
pnpm dev mcp-serve --type http --port 3000

# Run with SSE transport
pnpm dev mcp-serve --type sse --port 3000

Build

pnpm build

Test

pnpm test

Usage with Claude Code

Add to your Claude Code configuration:

{
  "mcpServers": {
    "imagine-mcp": {
      "command": "node",
      "args": ["/path/to/imagine-mcp/dist/cli.cjs", "mcp-serve"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Available Tools

unsplash_search

Search for stock images from Unsplash.

Parameters:

• query (required): Search query (e.g., "sunset", "technology", "nature")
• perPage (optional): Number of results per page (1-30, default: 10)
• page (optional): Page number for pagination (default: 1)
• orientation (optional): Filter by photo orientation ("landscape", "portrait", "squarish")
• color (optional): Filter by photo color ("black_and_white", "black", "white", "yellow", "orange", "red", "purple", "magenta", "green", "teal", "blue")

Example usage in Claude Code:

Search Unsplash for sunset photos
Search Unsplash for landscape technology images
Find portrait photos of people in blue tones

Response includes:

• Image ID and description
• Photographer name and profile
• Image dimensions and color
• URLs for different sizes (full, regular, small, thumbnail)
• Links to view on Unsplash and download
• Like count

read-image

Read image data from different sources and return metadata.

Parameters:

• source (required): File path, URL, or data URI
• includeBase64 (optional): Set true to include base64 output in response

Response includes:

• source: original source input (normalized path or URL)
• sourceType: "file" | "url" | "data-uri"
• mimeType: detected MIME type
• sizeBytes: byte length
• sha256: SHA-256 hash of bytes

Adding New Tools

To add new image generation or manipulation tools:

1. Create a new tool:

   # Use the scaffold feature
   nx run imagine-mcp:list-scaffolds
   # Or manually create in src/tools/

2. Register the tool in src/server/index.ts

3. Build and test

License

AGPL-3.0