npm package: @qingchencloud/qtpixel-mcp
Description: MCP Server for QT Pixel - AI Pixel Art Generator
Author: QingChen Cloud
Latest version: 1.0.0

# @qingchencloud/qtpixel-mcp

QT Pixel MCP Server - AI Pixel Art Generator for Model Context Protocol.

This MCP server allows AI assistants (like Claude, Cursor) to generate pixel art images through the QT Pixel API.

## Features

- **Single Image Generation**: Create pixel art from text prompts
- **Batch Generation**: Generate multiple images at once (1-4 images)
- **Variations**: Create variations of the same subject
- **Task Management**: Check status and list your artworks

## Installation

```bash
npm install -g @qingchencloud/qtpixel-mcp
```

Or use with npx (no installation required):

```bash
npx @qingchencloud/qtpixel-mcp
```

## Configuration

### Get Your API Key

1. Register at [QT Pixel](https://pixel.qingchencloud.com/register)
2. Go to Settings page
3. Copy your API Key

### Configure in Claude Desktop

Add to your Claude configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "qtpixel": {
      "command": "npx",
      "args": ["-y", "@qingchencloud/qtpixel-mcp"],
      "env": {
        "QTPIXEL_API_KEY": "gpa_your_api_key_here",
        "QTPIXEL_API_BASE": "https://pixel.qingchencloud.com"
      }
    }
  }
}
```

### Configure in Cursor

Add to your Cursor settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "qtpixel": {
      "command": "npx",
      "args": ["-y", "@qingchencloud/qtpixel-mcp"],
      "env": {
        "QTPIXEL_API_KEY": "gpa_your_api_key_here",
        "QTPIXEL_API_BASE": "https://pixel.qingchencloud.com"
      }
    }
  }
}
```

## Available Tools

### create_pixel_art

Generate a single pixel art image.

**Parameters:**
- `prompt` (required): Description of the pixel art (e.g., "a cute cat")
- `background`: "transparent" or "white" (default: "transparent")
- `wait_for_completion`: Wait for generation to complete (default: true)

**Example:**
```
Create a pixel art of a red mushroom
```

### batch_generate

Generate multiple pixel art images at once.

**Parameters:**
- `prompt` (required): Description of the pixel art
- `count`: Number of images (1-4, default: 2)
- `variations`: Generate variations (default: true)
- `background`: "transparent" or "white" (default: "transparent")

**Example:**
```
Generate 4 variations of a cute pixel cat
```

### get_task_status

Check the status of a generation task.

**Parameters:**
- `task_id` (required): The task ID

### get_batch_status

Check the status of a batch generation.

**Parameters:**
- `batch_id` (required): The batch ID

### list_my_artworks

List your previously generated artworks.

**Parameters:**
- `page`: Page number (default: 1)
- `status`: Filter by status (pending, processing, completed, failed)

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `QTPIXEL_API_KEY` | Yes | Your QT Pixel API key |
| `QTPIXEL_API_BASE` | No | API base URL (default: https://pixel.qingchencloud.com) |

## Examples

### Using with Claude

```
User: Create a pixel art of a blue space invader

Claude: [Uses create_pixel_art tool]
Here's your pixel art! 
Image URL: https://pixel.qingchencloud.com/static/gallery/123.png
```

### Batch Generation

```
User: I need 4 different pixel art characters for my game

Claude: [Uses batch_generate tool with count=4]
Generated 4 pixel art images:
1. https://pixel.qingchencloud.com/static/gallery/124.png
2. https://pixel.qingchencloud.com/static/gallery/125.png
3. https://pixel.qingchencloud.com/static/gallery/126.png
4. https://pixel.qingchencloud.com/static/gallery/127.png
```

## Support

- Website: https://pixel.qingchencloud.com
- API Documentation: https://pixel.qingchencloud.com/docs/api
- GitHub: https://github.com/1186258278/GoPixelArt

## License

MIT License - QingChen Cloud