imgui-mcp

<p align="center"> <h1 align="center">🎮 imgui-mcp</h1> <p align="center"> <strong>The MCP server that lets AI agents <em>see</em>, <em>build</em>, and <em>iterate</em> on Dear ImGui game UIs in real-time.</strong> </p> <p align="center"> <a href="https://github.com/SaloQT/imgui-mcp/releases"><img src="https://img.shields.io/github/v/release/SaloQT/imgui-mcp?style=flat&colorA=222222&colorB=58A6FF" alt="Release"></a> <a href="https://github.com/ocornut/imgui/releases/tag/v1.92.8"><img src="https://img.shields.io/badge/Dear_ImGui-v1.92.8-ff69b4?style=flat&colorA=222222" alt="ImGui"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-2025--06--18-orange?style=flat&colorA=222222" alt="MCP"></a> <img src="https://img.shields.io/badge/74_tools-8A2BE2?style=flat&colorA=222222" alt="Tools"> <img src="https://img.shields.io/badge/102_widgets-DC143C?style=flat&colorA=222222" alt="Widgets"> <img src="https://img.shields.io/badge/13_IDE%2FCLI_tools-3FB950?style=flat&colorA=222222" alt="Supported Tools"> <a href="https://github.com/SaloQT/imgui-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=flat&colorA=222222" alt="License"></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> · <a href="#all-74-mcp-tools">All Tools</a> · <a href="#all-102-widget-types">All Widgets</a> · <a href="#game-ui-patterns">Game Patterns</a> · <a href="#supported-idecli-tools">Supported Tools</a> · <a href="https://github.com/SaloQT/imgui-mcp/releases">Releases</a> </p> </p>

---

The Problem

AI coding agents can generate UI code — but they can't see the result. They write ImGui calls blind, hope the layout works, and never iterate visually. Game UI development needs a feedback loop: place → preview → adjust → repeat.

The Solution

imgui-mcp is a Model Context Protocol server that gives any AI agent a live, interactive Dear ImGui canvas with 84 tools, 102 widget types, and a visual feedback loop:

┌──────────────────────────────────────────────────────────────────┐
│  "Build a game HUD with health bar, inventory, and skill bar"    │
└───────────────────────────────┬──────────────────────────────────┘
                                ▼
┌─────────────┐    MCP     ┌──────────┐   JSON    ┌─────────────┐
│  AI Agent   │◄──────────►│ server.py │◄────────►│  Live ImGui  │
│  (any LLM)  │  84 tools  │ 0 deps   │  stdin/  │  SDL2+GL     │
└─────────────┘            └──────────┘  stdout   └──────┬───────┘
       ▲                                                 │
       │              screenshot (BMP)                   │
       └─────────────────────────────────────────────────┘
                    Agent SEES what it built

The agent creates widgets, takes a screenshot, sees the rendered result, and iterates — like a developer with eyes.

---

Features at a Glance

| | | |---|---| | 🖼️ Visual Feedback | Screenshot capture (full frame, widget-bound metadata, annotated overlays) — the agent sees its work | | 🎮 Game UI Patterns | Health bars, mana bars, inventory grids, dialogue boxes, minimaps, cooldown radials, skill bars, quest trackers, character sheets, notification toasts, tooltip cards | | 🖱️ Input Simulation | Click buttons, type text, hover widgets, scroll, press keys — test UI behavior programmatically | | ✨ Animation | 7 easing functions, nested-widget property tweens, loop/ping-pong, and JSON round-trip persistence | | 🎨 Theming | 7 presets (dark, light, classic, fantasy, sci-fi, retro, minimal) + per-color and per-variable customization | | 📐 Layout | 9-point anchor system, resolution presets (720p → 4K + ultrawide + mobile), DPI scaling, safe areas | | 🔄 Workflow | Undo/redo (50-deep), named snapshots, save/load/delete layout versions | | 🎬 Scenes | Multi-window composition, z-order layers, conditional visibility (widget.checked==true) | | 📦 Export | Generate production C++, Lua, or complete JSON designs with fonts and live animations | | 🖌️ Drawing | Lines, rects, circles, triangles, beziers, polylines, text — direct ImDrawList access | | 🧩 102 Widgets | Every Dear ImGui widget + 11 game-specific patterns | | 🔌 Zero Dependencies | Python server needs no pip packages. C++ app vendors ImGui. | | 🪟 Native Polish | Dark themed Windows title bar, branded taskbar/title-bar icon, and HiDPI-aware windowing | | 🔤 Font Stacks | Runtime TTF/OTF loading, Unicode coverage presets, and merged icon/symbol fallback faces |

---

Quick Start

Option A: Pre-built release (no compiler needed)

Download from Releases:

Linux:

tar -xzf imgui-mcp-*-linux-x64.tar.gz
cd imgui-mcp-*-linux-x64
./setup.sh    # configures all 13 IDE/CLI tools

Windows:

Extract zip → double-click install.bat

Option B: Build from source

git clone https://github.com/SaloQT/imgui-mcp.git
cd imgui-mcp
uv sync       # installs the pinned official MCP Python SDK
make build    # requires: cmake, g++, libsdl2-dev, libgl1-mesa-dev
./setup.sh

Verify it works

uv run python demo.py   # runs a full feature demonstration

---

All 74 MCP Tools

Windows & Widgets (7)

| Tool | Description | |------|-------------| | imgui_create_window | Create a window with title, position, size, and flags (menubar, no_resize, no_move, no_collapse, no_title_bar, always_auto_resize) | | imgui_add_widget | Add any of 102 widget types to a window — supports nested children for containers | | imgui_update_widget | Update a widget's value, text, checked state, color, label, or enabled state at runtime | | imgui_remove_widget | Remove a widget by ID | | imgui_remove_window | Remove a window and all its widgets | | imgui_get_state | Get the full state of every window and widget (values, clicked, changed, hovered, focused) | | imgui_clear_all | Remove all windows and widgets, reset to empty canvas |

Visual Feedback (3)

| Tool | Description | |------|-------------| | imgui_screenshot | Capture the current frame as BMP — agent can inspect the image to see what it built | | imgui_screenshot_widget | Capture with a specific widget's bounding box info for targeted inspection | | imgui_screenshot_annotated | Capture with widget ID overlays drawn on the image for spatial reference |

Input Simulation (7)

| Tool | Description | |------|-------------| | imgui_click_widget | Simulate a mouse click on any widget (finds its rect center, injects click events) | | imgui_type_text | Focus a widget and type text into it character by character | | imgui_hover_widget | Move the virtual mouse to hover over a widget (triggers tooltips, highlights) | | imgui_scroll_window | Inject mouse wheel scroll into a window | | imgui_press_key | Press any key or combo: Enter, Tab, Escape, Ctrl+S, Shift+A, etc. | | imgui_set_mouse_pos | Set the virtual mouse position in screen coordinates | | imgui_focus_widget | Set keyboard focus to a specific widget for the next frame |

Window & Widget Manipulation (8)

| Tool | Description | |------|-------------| | imgui_move_window | Move a window to new (x, y) coordinates | | imgui_resize_window | Resize a window to new (w, h) dimensions | | imgui_move_widget | Offset a widget's position via cursor offset | | imgui_get_widget_rect | Get a widget's actual rendered bounding box in pixels | | imgui_get_window_rect | Get a window's position and size | | imgui_bring_to_front | Focus and raise a window to the top | | imgui_set_widget_size | Override a widget's dimensions | | imgui_get_layout | Get all widget bounding boxes in a window as structured data |

Drawing — ImDrawList (1)

| Tool | Description | |------|-------------| | imgui_draw | Draw on named, composable canvas layers. Calls append by default (mode: replace resets one layer). Includes lines, rectangles, circles, triangles, text, polygons, Beziers, ellipses, arcs, and four-corner gradients |

Interactive Canvas (10)

| Tool | Description | |------|-------------| | imgui_add_hit_region | Add an invisible interactive shape (rect, circle, ellipse, polygon) that detects hover, click, drag, double-click, and wheel events. Supports transforms (position, rotation, scale). | | imgui_remove_hit_region | Remove a hit region by id | | imgui_update_hit_region | Update a hit region's shape, transform, or interaction flags | | imgui_get_canvas_events | Drain canvas interaction events (hover, click, drag start/move/end, wheel, double-click) with positions and deltas | | imgui_update_draw_command | Update a single draw command in a layer by index — change color, position, thickness without replacing the layer | | imgui_transform_draw_layer | Apply translate, rotate, scale, or opacity to an entire draw layer | | imgui_bind | Bind a widget value to a visual property (e.g. slider → draw layer opacity). Updates every frame automatically. | | imgui_unbind | Remove bindings by source widget and/or target | | imgui_set_callback | Declarative action: button click toggles visibility, switches scenes, or sets values — no polling round-trip | | imgui_remove_callback | Remove declarative callbacks |

Style & Theming (7)

| Tool | Description | |------|-------------| | imgui_set_style | Apply a built-in theme: dark, light, or classic | | imgui_set_theme | Apply an extended theme preset: fantasy (gold/amber), scifi (cyan/teal), retro (terminal green), minimal (clean white) | | imgui_set_theme_color | Set any ImGui color by name: WindowBg, Button, Text, FrameBg, Header, Border, etc. | | imgui_set_style_var | Set any style variable: FrameRounding, WindowRounding, ItemSpacing, FramePadding, IndentSpacing, ScrollbarSize, GrabMinSize, etc. | | imgui_push_style_color | Push a temporary style color override | | imgui_pop_style_color | Pop pushed style colors | | imgui_set_background | Set the viewport background clear color |

Animation (3)

| Tool | Description | |------|-------------| | imgui_animate | Tween any widget property (value, opacity, size, position) over time with easing: linear, ease_in, ease_out, ease_in_out, bounce, elastic, back — supports loop/ping-pong | | imgui_stop_animation | Stop animations on a specific widget | | imgui_stop_all_animations | Stop all active animations |

Layout & Responsiveness (7)

| Tool | Description | |------|-------------| | imgui_set_anchor | Anchor a window to the viewport: top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right — with pixel offset | | imgui_set_widget_anchor | Anchor a widget within its window for responsive layout | | imgui_set_viewport_size | Resize the application window to exact pixel dimensions | | imgui_get_viewport_size | Get current viewport dimensions | | imgui_set_resolution_preset | Resize to a preset: 720p, 1080p, 1440p, 4k, ultrawide (3440×1440), mobile (390×844), tablet (1024×768) | | imgui_set_dpi_scale | Scale all UI sizes for HiDPI displays (1.0, 1.5, 2.0) | | imgui_set_safe_area | Set safe area insets (top, bottom, left, right) that anchored windows respect |

Assets, Textures & Fonts (5)

| Tool | Description | |------|-------------| | imgui_load_texture | Load a BMP/PPM image as a GPU texture for Image/ImageButton widgets. Creates a checkerboard placeholder if file not found. | | imgui_unload_texture | Free a loaded texture's GPU resources | | imgui_load_font | Load a TTF/OTF font with a glyph-coverage preset, or merge it into another face as a symbol/icon fallback. | | imgui_set_font | Switch the global ImGui fon