appinspire-mcp

Give Claude and Codex a real mobile design reference library before they write UI.

A local MCP server inspired by inspo-mcp's reference-first workflow, adapted for iOS, Android and cross-platform apps. Search attributed Behance projects, Dribbble shots, Apple Design Award winners and finalists, and other public mobile design resources. Inspect source previews, choose an original direction, then create phone-first UI with coherent typography, motion and rich tactile feedback. A mobile design, mockup or prototype request calls for a reviewable visual or interactive preview, without implicit native compilation. When the user requests a runnable native app, use the project's mobile framework and verify the requested native runtime. A desktop website layout does not become mobile UI through resizing or a WebView.

No API key, hosted backend, subscription or database is needed. Search and guidance work offline. Bundled references fetch previews from their publishers. Collected research libraries also serve local images offline. An attributed appinspire edition of the LottieFiles motion-design skill is served offline; the unmodified upstream skill is included beside it.

Install

Requires Node.js 22+ and the Codex CLI and/or Claude Code CLI. Install the package durably, then register it:

npm i -g appinspire-mcp
appinspire-mcp install

Upgrade by installing the new release and rerunning the installer:

npm i -g appinspire-mcp@latest && appinspire-mcp install

install registers the installed package in both clients through their official configuration commands, with absolute paths. The Node path is chosen to survive Node upgrades: Homebrew's formula opt link, or an unversioned node on PATH, when it resolves to the Node running the installer; otherwise that Node's own path, with a warning that a Node upgrade needs another appinspire-mcp install. MCP startup runs locally without npm, version resolution, install hooks or downloads. Keep the registered package and Node installation in place. After registering the clients, the same command installs the research library into ~/.appinspire-mcp/library (about 700 MB once; upgrades download only changed archives). A library download failure never fails registration; --skip-library or APPINSPIRE_SKIP_LIBRARY=1 defers it and appinspire-mcp library install installs or retries it. The package has no npm install hook (npm 12 skips dependency install scripts anyway), so npm i and npx never download the library by themselves.

The result's warnings never fail installation. npx-cache means the installer ran from npx's cache, which npx rewrites; install with npm i -g instead. claude-multiacc means a client resolves into a claude-multiacc installation, whose synced registry pushes the registration, with this machine's paths, to every machine in its pool. On Macs where app-robot's runner publishes appinspire-mcp into claude-multiacc pools, do not run appinspire-mcp install; the runner manages appinspire-mcp per machine.

Start a new client session to load the tools. Install for just one client or inspect the commands first:

appinspire-mcp install --client codex
appinspire-mcp install --client claude
appinspire-mcp install --dry-run
appinspire-mcp doctor

For a checkout or local package, including before the first npm release:

npm ci
node bin/appinspire-mcp.mjs install --local

For any other stdio MCP client, use the absolute Node and package entry paths shown by install --dry-run, with serve as the final argument. See installation for the Node path choice, warnings, manual configuration, removal and the distinction between registration and a working connection.

Collect a local screen library

Install first, then run the collectors for the sources you want:

appinspire-mcp install
appinspire-mcp collect appshot --limit 20
appinspire-mcp collect adapty --limit 20
appinspire-mcp collect paywall-gallery --help

The collectors keep third-party metadata and media in ~/.appinspire-mcp/library, or APPINSPIRE_LIBRARY_DIR when configured. Collector arguments pass through unchanged; each source's --help describes its options. Downloaded libraries remain local and are not bundled in npm. Installation installs the research library release; server startup never downloads, and neither runs collectors or synchronizes collections. See installation for storage setup.

Reference libraries

Four reference sources are first class: Appshot store campaigns, Adapty paywalls, and the PaywallPro gallery's paywall previews and onboarding frames. Every source is covered by a negotiated agreement with its owner, so the media may be collected and distributed as versioned library bundles to the machines that run this server.

Attribution travels with the media: each source keeps its LICENSE.upstream, its per-reference attribution field and the collector's permission note in manifest.json. The agreements cover this distribution, not further redistribution of the source images or any claim over the original designs. The npm package itself still carries no third-party media; libraries live in APPINSPIRE_LIBRARY_DIR or ~/.appinspire-mcp/library.

Use it

Ask your coding client:

Use appinspire-mcp to design a thoughtful iPhone hiking journal with a route overview, journal entries and saved walks.

A short product prompt is enough. Codex or Claude supplies research, an original concept, concrete visual decisions and expressive animation without asking you to prescribe typography, palettes or choreography. It records those choices in existing project notes and carries them into the implementation. Good existing brand direction and explicit product requirements take priority; unspecified details remain proposals. The AI chooses and implements missing creative details autonomously, without waiting for the user to explain design or animation.

The intended sequence is:

1. get_guidelines — read the core once: art direction, the search and sensory-coverage process, the accessibility modes and the review loop. Add the surface topic for each further surface and every topic the core marks required.
2. recommend — turn a product brief into references matched to its subject and screens, the guidance calls for every declared surface, a token method and a referencePlan explaining each match.
3. get_screen — view actual attributed image content when the source permits it.
4. compare and find_similar — study alternatives and select useful principles.
5. get_design_system, find_patterns, get_mechanics_recipe — plan the implementation.
6. get_motion_guidance — read the motion skill edition and author signature choreography, haptics and sound for each surface.
7. build_design_brief — assemble the chosen references and acceptance criteria for the coding client.
8. Render a representative phone screen and record a meaningful interaction from before its trigger. Watch it at normal speed and reconcile it with the choreography through check_motion_capture. Judge composition, reference adaptation and motion quality separately from functional test results. Proceed when the concept works, refine weak execution, or rethink a generic or unsuitable concept before expanding it; repeat review and revision until no reviewer finds a blocker or major issue. Complete the requested preview or app and verify affected output in its actual runtime.

To finish sooner, a client may split the work across parallel agents or threads. get_guidelines returns the workPlan rules and the brief tools return its steps. The order is: shared values in the project's own sources first; the representative screen and recurring parts before the rest; drafts until that decision; reviews only on real artwork and copy; captures from the final interface; and a side-by-side comparison of everything built. A client without parallel agents runs the same steps in order. Splitting never reduces what is designed or checked.

Match verification to the deliverable. Design previews need rendered design evidence; runnable native apps also need native interaction evidence. Browser previews cannot prove native behavior. Use the existing workflow and record only checks actually performed; this does not require a new framework, approval step or test infrastructure.

Keep the main task and a useful action in the initial mobile viewport at normal text size. Use navigation for the product and handle back behavior, insets and keyboards in the implemented runtime. Adapt larger windows as the same product; avoid turning them into a landing page. No fixed tab bar, component kit or visual preset is required.

When the request specifies an outcome or screens, the client supplies the optional product input to recommend and build_design_brief. Explicit requirements drive the returned intent and screen structure; pattern suggestions stay separate. Category inference reports keyword ties and unsupported categories openly. See the product contract for the shared schema and an example.

The guidance sets completeness and a search process, not a style. The client explores several fundamentally different metaphors, beyond the product's category, until the concept is unmistakably the product's own. It inventories every interactive element and state change and gives each a designed motion, haptic and sound decision, or records why it stays silent; there is no minimum or maximum number of effects. Scope stays with the request: no unrequested screens or features, while states, transitions, micro-interactions, haptics, sound, empty and error screens and polish are never extra scope.

Generated app UI, onboarding and paywalls target expressive, implemented motion even when a short brief does not mention animation. Each key action gets signature choreography derived from the product metaphor: trigger, elements, progression, timing/easing justified from the concept, outcome, interruption, haptic and sound cues and the reduced-motion alternative. A system or library default curve is not an authored choice. Explicit user and brand constraints take precedence; a sensitive product does not imply negligible animation. Review a meaningful state change at normal speed, including its entry and completion, before extending the design. Small transitions or passing tests alone do not establish compelling motion. A motion specification or a still screenshot cannot prove the result.

Reduced motion is a separately designed mode, applied invisibly from the OS preference and never a reason to shrink the main one. WCAG 2.2.2 governs automatic motion that runs for more than five seconds beside other content; longer background animation is fine when an inactive scene, the reduced mode or a legitimate product control stops it. Haptics are built from primitives (intensity, sharpness, duration, rhythm and binding to data) on one intensity scale shared with motion and sound, with continuous response during gestures and an AHAP handoff. Respect haptic preferences, avoid repeated buzzing and false success, and record every silence with its reason. Sound is a default layer delivered as a sound map and files; browser previews stay silent, as iOS silent mode requires. Physical tactile quality needs supported-device review; a recording or simulator cannot prove it. No extra native build is implied by a design request. See motion, haptic and sound implementation and verification.

get_guidelines with topic: "quality-gates" returns the required qualityGates: sensory coverage, signature motion, and checks from demo QA for visible focus after navigation, readable compact paywalls, visible and announced asynchronous results, text scaling, selected/focus contrast, consistent motion preferences, purposeful haptic feedback, clear product copy, and finished product UI. Apply every gate to each requested app, onboarding and paywall surface and retain the observed result. Receiving the checklist does not mean an app passed it. See rendered acceptance checks.

Create bespoke typography, colors, components and motion that express the chosen art direction. Accessibility must preserve readable, focusable controls without forcing generic OS styling. Appearance modes are optional; neither automatic dark mode nor a theme selector is required. Adapt the interface across phone and tablet sizes. Keep QA controls, debug/prototype labels, simulated-error switches and fake device chrome outside product UI. Use relevant existing previews, OS settings or recordings; keep any testing harness outside the product.

The server supplies evidence and structured guidance. Claude or Codex creates and checks the requested design or app. It does not make model API calls or claim that metadata alone guarantees a good visual result.

Tools and resources

| Purpose | Tools | | --- | --- | | Research | recommend, search_screens, get_screen, find_similar, compare | | Implement | build_design_brief, get_design_system, find_patterns, get_guidelines, get_mechanics_recipe | | Explore | get_filters, list_collections, get_collection, list_sources, discover | | Store campaigns | search_store_screenshots, get_store_screenshot | | Paywalls | search_paywalls, get_paywall | | Onboarding flows | search_onboarding, get_onboarding | | Motion | get_motion_guidance, check_motion_capture |

There are 23 tools, a design_mobile_app prompt, and JSON resources at appinspire://catalog, appinspire://sources, appinspire://libraries and appinspire://reference/{id}. See the API contract. The offline motion index is appinspire://motion; appinspire://motion/{topic} serves AppInspire's application guidance followed by the edition of that motion document.

get_guidelines answers with a compact core per surface and one topic per call (motion, haptics, sound, quality-gates, platform, artwork, surface), so no response repeats a rule. Pass the facts you know as constraints: appearances, locales, platforms, single-file HTML, external assets, a negotiated haptic bridge and store-campaign counts. They shape the answer, for example a right-to-left locale adds a mirrored-layout check and a single-file deliverable sets the core's delivery.files; each fact left out stays the author's decision, never a default. See consumer constraints. recommend and build_design_brief list the exact guidance calls for every declared surface instead of embedding them. get_mechanics_recipe returns invisible browser-preview mechanics (FLIP, gesture springs, gestures, scroll-linked progress, the reduced-motion mode, haptic cues and sensory event routing) whose every value is an authored parameter. check_motion_capture compares a recorded preview with the author's choreography specification and reports match, mismatch, not-detected or capture-too-late per check, without scoring the motion.

Original artwork uses the image-generation tool supplied by the host, with its pinned model and settings; when none is supplied, use the client's own tool. The artwork topic covers the brief, image-header checks and rendered integration. The standalone image command remains available.

Use the dedicated surface tools to inspect complete store campaigns, individual paywalls or ordered onboarding frames. Store campaigns use real app captures; paywalls use the product's actual offers; icons follow the chosen brand direction and the client's asset-generation tools. See local research libraries for collection, deduplication, source revenue labels and explicit missing-frame reports. Onboarding frames come from the PaywallPro agreement in their upstream order; entries whose manifest carries no frames are reported as missing coverage rather than invented.

get_design_system ships no palette, typeface, scale or component look. It returns semantic color roles and a method for deriving them from the product, authoring instructions for typography, spacing and shape, and platform units, with pointers to platform, motion and quality-gates topics. Choose a coherent product appearance rather than inheriting OS styling. Motion timing and easing are null, not zero: the client authors them from the concept. A requested style or motion personality is a description of the product; no preset stands behind it. See the motion contract for the nullable fields.

The MCP instructs the client to work as a senior, highly experienced art director: consider and design every screen, state and interaction, and search until the concept is unmistakably this product’s own. Server instructions and the get_guidelines core set concrete standards for original composition, typography, spacing, finished states, rendered critique and iteration; every design brief names that call first. Motion guidance is framework agnostic: implement it with the project's native animation facilities, CSS, or an appropriate animation library. The motion skill does not require a Lottie player for every animation. Its appinspire edition carries no archetype, preset or default value; product context and AppInspire's integration rules take precedence over any example in it. No house font, palette, mascot, card/pill layout or gradient treatment is supplied. Each motion sequence decides its layers and records why any layer stays empty. Visual ambition is judged against the actual brief and inspected references, independently of functional checks. Tempo, Lilt and other strong examples establish a standard of craft, not palettes, mascots, layouts or animation sequences to clone. Each product needs its own rationale and coherent identity. These instructions guide client decisions; they do not guarantee aesthetic quality or establish that newly generated output has been validated.

Reference library

The initial snapshot contains 413 references: 144 Behance projects, 75 Dribbble shots, 128 Apple award apps and games, and 66 additional references. It includes 400 preview URLs and 598 App Store screenshot links. Use get_screen with imageIndex to inspect additional screenshots of an app.

The bundled JSON catalog includes source URLs, creator or publisher attribution, provenance and verification dates. Individual records distinguish source evidence from editorial tags and adaptation suggestions. Apple awards identify the year and whether each entry won or was a finalist. Game references are tagged. App references, component patterns, official samples and directory links carry distinct kind values where applicable.

appinspire-mcp stats
appinspire-mcp search "travel itinerary"

The library is a curated snapshot, not an exhaustive ranking of every app. Search is lexical, similarity uses tags, and recommendations match the brief's own subject terms and each screen's pattern; a category word only reorders them. The server ships no design tokens and never measures source colors. discover provides external search links to expand research; it does not pretend to fetch fresh results. Source previews can be covers or collages, and publishers may block automated access or change URLs. When preview loading fails, the tool returns the original link and an explicit reason.

Community collection notes and award collection notes document coverage and repeatable collection commands. Full third-party galleries may require their own account. No access controls are bypassed, and third-party image assets are not bundled in the npm package.

Development and verification

npm ci
npm test
npm run check
npm run test:live
npm pack --dry-run

Tests exercise catalog retrieval, design guidance, isolated client installation and the actual MCP stdio protocol. The live check separately reports public preview availability. It is intentionally excluded from offline CI because publisher availability is outside this package's control.

Plans and task specifications live in docs/plans/; package.json excludes them from the npm package, and test/package-files.test.mjs checks the packed file list.

Local demos generated through the installed clients belong in gitignored demo/codex and demo/claude. Rendered screenshots and interaction evidence stay with their demos; task logs stay in .artifacts/. The motion demonstration directories are demo/codex/kinetic (Tempo) and demo/claude/kinetic (Lilt), each covering app UI, onboarding and a paywall. Existing demos stay intact. Their local verification reports record the rendered and reduced-motion checks actually performed.

Release through GitHub Actions after the Node 22/24 verification jobs pass. See publishing for npm trusted publishing and bootstrap authentication requirements.

The app-robot integration review describes factory wiring, design guidance ownership and the verification needed before migrating existing instructions.

Attribution

Independent implementation inspired by inspo-mcp; no implementation code was copied. Package code and original mechanics recipes are MIT licensed. Reference artwork, app names and trademarks belong to their creators. Study the principles and create original work; this index grants no reuse rights to source assets. The separately attributed LottieFiles motion-design skill is vendored unmodified under its MIT license, and the served appinspire edition is a modified, attributed version under the same license. See motion for the offline skill edition and implementation workflow. See NOTICE and each reference's attribution.