# Pixola MCP Server

> The Pixola MCP server lets AI assistants (ChatGPT, Claude, Cursor, VS Code, Windsurf, etc.) generate images and manage your Pixola account directly via the Model Context Protocol.
> Endpoint: https://www.pixola.ai/mcp
> Transport: Streamable HTTP (POST)
> Auth: Bearer token with pxk_ API key
> Docs: https://www.pixola.ai/docs/mcp

## Per-Platform Setup Guides

- ChatGPT: https://www.pixola.ai/docs/chatgpt
- Claude Desktop: https://www.pixola.ai/docs/claude
- Claude Code: https://www.pixola.ai/docs/claude-code
- Cursor: https://www.pixola.ai/docs/cursor
- Windsurf: https://www.pixola.ai/docs/windsurf
- VS Code / GitHub Copilot: https://www.pixola.ai/docs/vscode

## Prerequisites

1. Create a Pixola account at https://www.pixola.ai (free tier includes 1,000 credits)
2. Go to Settings → API Keys (https://www.pixola.ai/settings) and create a key
3. The key starts with pxk_ and is shown only once — save it somewhere safe

## How Pixola MCP works

Pixola can be used in two ways:

- **Remote MCP (hosted):** Your AI app talks over the internet to Pixola's server at https://www.pixola.ai/mcp. You add the URL and your API key in the app's config. No local install. Used by: ChatGPT, Cursor, Windsurf, VS Code, Claude Code, and Claude Desktop (manual config).
- **Local MCP (Claude Desktop only):** The .mcpb extension installs a small server that runs on your computer. That local server talks to Pixola's REST API (not the MCP URL). Used by: Claude Desktop when you install the one-click extension.

## Server Details (remote MCP)

- URL: https://www.pixola.ai/mcp
- Transport: Streamable HTTP (stateless, per-request)
- Auth: Authorization: Bearer pxk_YOUR_API_KEY
- Content-Type: application/json
- Accept: application/json, text/event-stream

## Setup: ChatGPT

Uses remote MCP (URL + API key). Requires ChatGPT Pro, Team, Enterprise, or Edu with Developer Mode enabled.

1. Open ChatGPT → Settings → Developer → MCP Servers
2. Click "Add MCP Server"
3. Enter URL: https://www.pixola.ai/mcp
4. Select "API Key" auth and paste your pxk_ key
5. Save — Pixola tools appear in your conversation tool picker

## Setup: Claude Desktop

Claude Desktop supports both options. Pick one:

**Option A — Local MCP (one-click):** Install the extension. A small server runs on your machine and calls Pixola's API. No config file.
1. Download the Pixola Desktop Extension: https://www.pixola.ai/downloads/pixola.mcpb
2. Double-click the .mcpb file to open it in Claude Desktop (or open Claude Desktop → Settings → Extensions and drag the file in)
3. Enter your Pixola API key when prompted (get one at https://www.pixola.ai/settings)
4. Click Install — no terminal or config editing

**Option B — Remote MCP (manual config):** Claude Desktop talks directly to https://www.pixola.ai/mcp over the internet. Add to your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

  {
    "mcpServers": {
      "pixola": {
        "url": "https://www.pixola.ai/mcp",
        "headers": {
          "Authorization": "Bearer pxk_YOUR_API_KEY"
        }
      }
    }
  }

## Setup: Claude Code

Uses remote MCP (URL + API key). Run in terminal (URL is a positional argument; do not use --url):

  claude mcp add pixola https://www.pixola.ai/mcp -t http -H "Authorization: Bearer pxk_YOUR_API_KEY"

Or with long options:

  claude mcp add pixola https://www.pixola.ai/mcp --transport http --header "Authorization: Bearer pxk_YOUR_API_KEY"

Restart your Claude Code session (/exit and relaunch) for the MCP server to appear.

Auto-allow all Pixola tools (optional): To avoid being prompted for each tool, add a wildcard to your project's .claude/settings.local.json. In the permissions.allow array, add:

  "mcp__pixola__*"

That allows all Pixola MCP tools (generate_image, list_models, check_credits, get_batch, list_images, get_image, list_styles, list_shapes) in one go. The same pattern works for any MCP server: mcp__<server-name>__*

## Setup: Cursor

Uses remote MCP (URL + API key). Add to .cursor/mcp.json in your project root:

  {
    "mcpServers": {
      "pixola": {
        "url": "https://www.pixola.ai/mcp",
        "headers": {
          "Authorization": "Bearer pxk_YOUR_API_KEY"
        }
      }
    }
  }

## Setup: Windsurf

Uses remote MCP (URL + API key). Add to ~/.codeium/windsurf/mcp_config.json:

  {
    "mcpServers": {
      "pixola": {
        "serverUrl": "https://www.pixola.ai/mcp",
        "headers": {
          "Authorization": "Bearer pxk_YOUR_API_KEY"
        }
      }
    }
  }

## Setup: VS Code / Copilot

Uses remote MCP (URL + API key). Add to .vscode/mcp.json in your project:

  {
    "servers": {
      "pixola": {
        "type": "http",
        "url": "https://www.pixola.ai/mcp",
        "headers": {
          "Authorization": "Bearer pxk_YOUR_API_KEY"
        }
      }
    }
  }

## Setup: Any MCP Client

For any client supporting remote MCP servers with Streamable HTTP transport:

- URL: https://www.pixola.ai/mcp
- Transport: Streamable HTTP (POST)
- Auth header: Authorization: Bearer pxk_YOUR_API_KEY
- Content-Type: application/json

Test with curl:

  curl -X POST https://www.pixola.ai/mcp \
    -H "Authorization: Bearer pxk_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

## Interactive Apps (MCP Apps)

On hosts that support MCP Apps, some Pixola tools render an interactive UI in the conversation — a form, gallery, or dashboard — instead of just text. No extra setup required. The same tools work on all hosts; supported hosts show the richer experience.

Tools with interactive UIs:
- generate_image — Image generator with model/style/shape pickers and live preview
- list_models — Filterable card grid of all 40+ models with pricing
- check_credits — Credits dashboard with balance and plan info
- list_images — Image gallery with thumbnails; click to expand
- get_image — Full image detail view with metadata

Supported hosts: Claude (web + Desktop via remote connector), VS Code Copilot, Goose, Postman, MCPJam.
Other hosts (ChatGPT, Cursor, Windsurf) receive the standard text response — no change to behavior.

## Available Tools

### generate_image(prompt, model?, style?, shape?, quality?)
Generate one or more AI images from a text prompt.
The tool automatically polls for results and returns image URLs when ready (up to 120s timeout).
- prompt (required) — descriptive text prompt
- model (optional) — model slug, e.g. "flux-2", "gpt-image-1.5". Use list_models to see options.
- style (optional) — style preset slug, e.g. "watercolor", "anime". Use list_styles to see options.
- shape (optional) — aspect ratio slug, e.g. "square", "landscape-wide". Use list_shapes to see options.
- quality (optional) — "standard" or "hd". HD uses more credits.
Returns: image URLs for each generated image.

### list_models()
List all available AI image generation models.
Returns: name, slug, description, best-for, standard credits, HD credits, whether reference images are supported.

### list_styles()
List all available style presets organized by category.
Returns: slug and name for each style, grouped by category.

### list_shapes()
List all available aspect ratio options.
Returns: slug, name, and aspect ratio for each shape.

### check_credits()
Check your current credit balance and subscription plan.
Returns: credit count, plan name, plan key.

### get_batch(batchId)
Check the status of an image generation batch and get image URLs when complete.
- batchId (required) — the batch ID returned from generate_image.
Returns: batch status and image URLs.

### list_images(limit?)
List your recently generated images.
- limit (optional) — max images to return, default 20, max 100.
Returns: list of images with title, model, and URL.

### get_image(imageId)
Get full details and download URL for a specific image.
- imageId (required) — the image ID.
Returns: title, model, status, prompt, URL, credits charged.

## Rate Limits

- 30 requests per minute per API key
- 1,000 requests per day per API key
Same limits as the REST API (https://www.pixola.ai/docs/api).

## Example Prompts for AI Assistants

Once configured, you can ask your AI:
- "Generate a widescreen landscape using FLUX 2 in watercolor style"
- "What models are available and how many credits do they cost?"
- "Show me my last 10 generated images"
- "How many credits do I have left?"
- "Generate 3 versions of a neon city at night using different styles"
- "Generate a portrait image using the gpt-image-1.5 model in HD quality"

## Claude Code Plugin

The Pixola plugin for Claude Code includes the MCP server connection plus expert skills:
- /pixola:generate-image — Expert image generation with model selection guidance and prompt tips
- /pixola:creative-brief — Multi-image workflow for brand assets, storyboards, and themed collections
- /pixola:model-guide — Model selection help based on style, quality, and budget

Install: /plugin install pixola

## Roadmap: Local MCP Package

The @pixola/mcp-server npm package (local stdio transport) is planned but not yet published.
The hosted remote server at https://www.pixola.ai/mcp works with all major MCP clients today.