playbooks

home / mcp / visualai mcp server

VisualAI MCP Server

Locally runs MLX-based image generation with MCP for Apple Silicon, enabling private model inference and iterative design tasks.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "alucardeht-frame-forge-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/visualai-workspace/dist/index.js"
      ],
      "env": {
        "PYTHON_PATH": "/path/to/python3",
        "MODEL_CACHE_DIR": "~/.cache/huggingface/"
      }
    }
  }
}

VisualAI MCP Server enables fully local, model-context-powered image generation on Apple Silicon. You run a local MCP server that talks to clients via the MCP protocol, giving you private, zero-cost inference with MLX acceleration.

How to use

You integrate the VisualAI MCP Server with your MCP client to generate images and manage iterations across sessions. Start the server once, then load it in your client’s MCP server list. You can generate images from prompts, monitor engine status, and manage multiple iterations within a session. Use the client to request new renders, preview past iterations, or rollback to a previous state within a session.

How to install

Prerequisites you need before installing: a Mac with Apple Silicon (M1, M2, M3, M4 or newer), macOS 12+ (Monterey or later), Node.js 18+, and Python 3.9+.

Then follow these concrete steps to install and prepare the server.

Installation steps

npm install
npm run build

Initial setup and startup

Start the setup flow to configure Python, install dependencies, and download models. This will run automatically when you first start the server and will guide you through validation and health checks.

Start the server to begin the setup wizard.

Configuration

Customize MCP server integration and paths if automatic injection is not available. The setup wizard can inject configuration into Claude Desktop, but you can also configure manually.

Claude Desktop integration

Platform-specific config paths where the VisualAI MCP server configuration is injected or stored.

Configuration details

{
  "mcpServers": {
    "visualai": {
      "command": "node",
      "args": ["/absolute/path/to/visualai-workspace/dist/index.js"],
      "env": {
        "PYTHON_PATH": "/path/to/python3",
        "MODEL_CACHE_DIR": "~/.cache/huggingface/"
      }
    }
  }
}

Start Server

Run the server in stdio mode to begin handling MCP requests.

Architecture

Engine: MLX on Apple Silicon, Model: Stable Diffusion 2.1, Protocol: MCP via stdin/stdout, Sessions stored under ~/.visualai/sessions, Typical turnaround is 8-15s per 512x512 image on capable Apple Silicon hardware.

Tools and endpoints overview

The server exposes a set of MCP tools for image generation and status checks. You can create, preview, and manage iterations across sessions.

Available tools

generate-image

Generate an image from a text prompt using the local MLX engine.

check-engine-status

Check the MLX engine and dependency status to ensure the environment is ready.

list-sessions

List all active MCP sessions with their metadata.

rollback-iteration

Revert a session to a previous iteration index.

preview-iteration

Preview a previous iteration without altering the session state.