smart-illustrator MCP — Use Cases, Install & Live Demo

Why use it

Key features

Intelligent position detection — picks where illustrations actually help the reader
Tri-engine routing: Gemini (creative), Excalidraw (sketchy), Mermaid (structured)
10+ illustration types: flowcharts, sequence diagrams, mindmaps, metaphors, covers
Cover generation tuned per platform (YouTube 16:9, WeChat 3:4, Twitter)
Prompt-only mode — output prompts for manual batch generation without API calls
Resume-safe: skip already-generated images when re-running

Live Demo

What it looks like in practice

smart-illustrator-skill.replay ▶ ready

0/0

Install

Pick your client

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

{
  "mcpServers": {
    "smart-illustrator-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/axtonliu/smart-illustrator",
        "~/.claude/skills/smart-illustrator"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "smart-illustrator-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/axtonliu/smart-illustrator",
        "~/.claude/skills/smart-illustrator"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "smart-illustrator-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/axtonliu/smart-illustrator",
        "~/.claude/skills/smart-illustrator"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "smart-illustrator-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/axtonliu/smart-illustrator",
        "~/.claude/skills/smart-illustrator"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "smart-illustrator-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/axtonliu/smart-illustrator",
        "~/.claude/skills/smart-illustrator"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "smart-illustrator-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/axtonliu/smart-illustrator",
          "~/.claude/skills/smart-illustrator"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add smart-illustrator-skill -- git clone https://github.com/axtonliu/smart-illustrator ~/.claude/skills/smart-illustrator

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use smart-illustrator

How to auto-illustrate a long-form blog post

👤 Technical writers and content creators publishing markdown articles ⏱ ~20 min beginner

When to use: You have a finished markdown article that needs 4-8 illustrations before publishing, and you don't want to hand-prompt each one.

Prerequisites

Skill installed under ~/.claude/skills/smart-illustrator — git clone https://github.com/axtonliu/smart-illustrator into that path
Gemini API key (for creative visuals) — Export GEMINI_API_KEY; skill reads from env
Mermaid CLI if you want diagram rendering — npm i -g @mermaid-js/mermaid-cli

Flow

Point the skill at your article

Run smart-illustrator on posts/2026-04-launch.md in article mode. Pick 5 illustration points.✓ Copied

→ Skill echoes chosen positions with one-line rationale each
Review engine choices

Show me which engine you picked for each illustration and why. Let me override any.✓ Copied

→ Per-position table: position → engine → reason
Generate and embed

Generate all images and write the updated markdown back to the same file.✓ Copied

→ Article updated with inline image references; PNGs saved under assets/

Outcome: A publishable markdown file with 5 context-appropriate illustrations and a cover image.

Pitfalls

Gemini returns a stock-looking image for an abstract concept — Re-run that single position with --engine excalidraw for a sketchy metaphor instead
Mermaid syntax fails to render because LLM mis-escaped quotes — Use --prompt-only for diagrams, paste into mermaid.live to debug, then re-inject

Combine with: banana-claude-skill

Generate platform-optimized covers for a post

👤 Creators repurposing one article across YouTube, WeChat, and Twitter ⏱ ~10 min beginner

When to use: You're about to cross-post and need the same concept rendered at 3 different aspect ratios and tones.

Prerequisites

Finished article title + 1-line hook — Prepare a short prompt; skill uses it as brief

Flow

Run cover mode for each platform

Use smart-illustrator in cover mode for title 'The 2AM Bug That Cost Us $40k' — generate for youtube, wechat, twitter.✓ Copied

→ 3 PNGs at correct resolutions, platform-appropriate composition
A/B variants

Regenerate the YouTube cover with 2 alternative angles so I can A/B test.✓ Copied

→ 3 thumbnails, visibly different

Outcome: A cover-pack ready to upload across channels without opening a design tool.

Pitfalls

Text on cover looks garbled — Gemini text rendering is unreliable — ask skill to add title as post-processing overlay instead

Turn a talk outline into slide infographics

👤 Speakers preparing technical talks from a markdown outline ⏱ ~25 min intermediate

When to use: You have a talk outline and want one infographic per key section before designing the deck.

Flow

Run slides mode

Take talk-outline.md, slides mode, one standalone infographic per H2 section.✓ Copied

→ One PNG per section, each self-contained
Refine weak ones

Section 3's infographic is too abstract. Re-do with Excalidraw engine, focus on the 3-step loop.✓ Copied

→ Hand-drawn replacement that matches outline

Outcome: A folder of slide-ready infographics keyed to your outline.

Pitfalls

Infographics don't match your deck's visual style — Pass --style='flat pastel' or a style reference image so outputs stay consistent

Combinations

Pair with other MCPs for X10 leverage

smart-illustrator-skill + banana-claude-skill

Use Smart Illustrator for diagrams and Banana Claude for photorealistic hero shots in the same post

For posts/launch.md, use smart-illustrator for the architecture diagram at section 2, then banana-claude for a photorealistic hero at the top.✓ Copied

smart-illustrator-skill + notebooklm-skill

NotebookLM researches the topic, Claude drafts the article, Smart Illustrator decorates it

Research 'CRDT conflict resolution' with notebooklm, draft a 2000-word article, then illustrate with smart-illustrator.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
detect_illustration_points	markdown_path: str, count?: int	First pass on any article to decide where images help	~2k Claude tokens
generate_illustration	position: str, engine: 'gemini'\|'excalidraw'\|'mermaid', prompt: str	Per chosen position after review	1 Gemini call or 0 (for Mermaid/Excalidraw)
generate_cover	title: str, platform: 'youtube'\|'wechat'\|'twitter', style?: str	Cover mode; call once per target platform	1 Gemini call
embed_into_markdown	markdown_path: str, illustrations: list	Final step after all images are generated	0

Cost & Limits

What this costs to run

API quota: Gemini free tier: 15 req/min, 1500/day. Mermaid/Excalidraw engines are free (local rendering).
Tokens per call: 2k-5k Claude tokens for position detection; image generation is separate Gemini quota
Monetary: Free with Gemini free tier. Paid Gemini ~$0.04 per image at current rates.
Tip: Use --prompt-only to draft all prompts, then batch-generate overnight to stay in free tier.

Security

Permissions, secrets, blast radius

Credential storage: GEMINI_API_KEY in shell env. No OAuth, no PATs.

Data egress: Article content is sent to Google Gemini for illustration prompts. Do not run on confidential drafts.

Article text is uploaded to Gemini — treat as public-grade content before running.

Troubleshooting

Common errors and fixes

Gemini 429 quota exceeded

Wait for daily reset or upgrade to paid tier. Use --engine mermaid|excalidraw for remaining positions.

Verify: curl -s https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY

Mermaid render fails with 'Parse error'

LLM produced invalid Mermaid. Use --prompt-only, paste into mermaid.live, fix syntax, regenerate.

Verify: mmdc -i test.mmd -o test.png

Skill not found by Claude Code

Confirm clone path is ~/.claude/skills/smart-illustrator and SKILL.md exists at root.

Verify: ls ~/.claude/skills/smart-illustrator/SKILL.md

Alternatives

smart-illustrator vs others

Alternative	When to use it instead	Tradeoff
banana-claude-skill	You only need photorealistic hero images, not diagrams	No position detection, no diagram engines
Manual Midjourney/DALL-E workflow	Your publication has a strict brand style guide that LLM routing won't respect	More control, much slower

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills