# Clone the repository
git clone https://github.com/takeshijuan/ideogram-mcp-server.git
cd ideogram-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Required
IDEOGRAM_API_KEY=your_ideogram_api_key_here

# Optional
LOG_LEVEL=info                    # debug, info, warn, error
LOCAL_SAVE_DIR=./ideogram_images  # Where to save images
ENABLE_LOCAL_SAVE=true            # Auto-download generated images

{
  "mcpServers": {
    "ideogram": {
      "command": "node",
      "args": ["/path/to/ideogram-mcp-server/dist/index.js"],
      "env": {
        "IDEOGRAM_API_KEY": "your_api_key_here"
      }
    }
  }
}

// Basic usage
{
  prompt: "A beautiful sunset over mountains"
}

// With all options
{
  prompt: "A cute cat wearing a wizard hat",
  aspect_ratio: "16x9",    // 15 ratios: 1x1, 16x9, 9x16, 4x3, 3x4, etc.
  num_images: 4,           // 1-8 images
  rendering_speed: "QUALITY", // FLASH, TURBO, DEFAULT, QUALITY
  magic_prompt: "ON",      // AUTO, ON, OFF - enhance prompts
  style_type: "REALISTIC", // AUTO, GENERAL, REALISTIC, DESIGN, FICTION
  character_reference_images: ["https://example.com/char.jpg"],
  save_locally: true       // Save to local disk
}

// Edit parts of an image using a mask
{
  prompt: "Add a red balloon in the sky",
  image: "https://example.com/photo.jpg",  // URL, file path, or base64 data URL
  mask: maskImageData,  // Black pixels=edit, White pixels=preserve
  rendering_speed: "DEFAULT",  // FLASH, TURBO, DEFAULT, QUALITY
  character_reference_images: ["https://example.com/char.jpg"],
  num_images: 1,
  magic_prompt: "AUTO",
  style_type: "AUTO"
}

{
  image: "https://example.com/photo.jpg",  // URL, file path, or base64
  describe_model_version: "V_3"  // "V_2" or "V_3" (default)
}
// Returns: array of text descriptions

{
  image: "https://example.com/photo.jpg",
  prompt: "High detail landscape",  // Optional guided upscaling
  resemblance: 70,  // 0-100: similarity to original (default 50)
  detail: 80,       // 0-100: detail enhancement level (default 50)
  magic_prompt: "ON",
  num_images: 1,
  save_locally: true
}

{
  image: "https://example.com/photo.jpg",
  prompt: "Transform into a watercolor painting",
  image_weight: 60,  // 0-100: influence of original image (default 50)
  aspect_ratio: "16x9",
  rendering_speed: "QUALITY",
  style_type: "FICTION",
  character_reference_images: ["https://example.com/char.jpg"],
  save_locally: true
}

{
  image: "https://example.com/square-photo.jpg",
  resolution: "1920x1080",  // Target resolution (required)
  rendering_speed: "DEFAULT",
  num_images: 1,
  save_locally: true
}

{
  image: "https://example.com/portrait.jpg",
  prompt: "A tropical beach at sunset",  // Describe the new background
  magic_prompt: "ON",
  rendering_speed: "QUALITY",
  num_images: 4,
  save_locally: true
}
// No mask needed - AI auto-detects foreground

{
  prompt: "A complex scene with many details",
  num_images: 8
}
// Returns immediately with prediction_id
// Poll with ideogram_get_prediction

{
  prediction_id: "pred_abc123..."
}
// Returns: status (queued/processing/completed/failed)
// When completed: includes images and cost

{
  prediction_id: "pred_abc123..."
}
// Only works for predictions in 'queued' status

{
  "total_cost": {
    "credits_used": 8,
    "estimated_usd": 0.08,
    "note": "Cost estimate based on known Ideogram pricing"
  }
}

# Development with hot reload
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

# Lint
npm run lint

# Format code
npm run format

# Test with MCP Inspector
npm run inspect

ideogram-mcp-server/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # MCP server setup
│   ├── config/           # Configuration
│   ├── services/         # Core services
│   │   ├── ideogram.client.ts    # API client
│   │   ├── cost.calculator.ts    # Cost estimation
│   │   ├── prediction.store.ts   # Async job queue
│   │   └── storage.service.ts    # Local file storage
│   ├── tools/            # MCP tools (10 tools)
│   │   ├── generate.ts
│   │   ├── generate-async.ts
│   │   ├── edit.ts
│   │   ├── describe.ts
│   │   ├── upscale.ts
│   │   ├── remix.ts
│   │   ├── reframe.ts
│   │   ├── replace-background.ts
│   │   ├── get-prediction.ts
│   │   └── cancel-prediction.ts
│   ├── types/            # TypeScript types
│   └── utils/            # Utilities
├── docs/                 # Additional documentation
├── dist/                 # Built output
└── package.json