# Pixelorama MCP

> An open-source Model Context Protocol (MCP) server that connects AI models to Pixelorama, enabling automated pixel art generation, layer management, and asset creation from plain text prompts.

- **Type:** MCP server
- **Install:** `agentstack add mcp-abidoo22-pixelorama-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [abidoo22](https://agentstack.voostack.com/s/abidoo22)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [abidoo22](https://github.com/abidoo22)
- **Source:** https://github.com/abidoo22/Pixelorama-MCP

## Install

```sh
agentstack add mcp-abidoo22-pixelorama-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🎨 pix-MCP

> **For the ones who can imagine it but can't draw it.**

pix-MCP is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that bridges AI assistants (Claude, GPT, Gemini, etc.) with [Pixelorama](https://www.pixelorama.org/), the free & open-source pixel art editor.

You describe what you want. The AI handles the rest — shapes, colours, shading, layers, animations, and full sprites — drawn live inside Pixelorama.

---

## ✨ Two Ways to Create

### 🤖 Way 1 — Describe it, AI draws it
Connect to Claude or any MCP client and describe your sprite in plain English:
> *"Draw a golden coin with a 3D star and drop shadow on a 64x64 canvas"*

The AI computes the geometry, shading, and outlines, then draws it pixel by pixel inside Pixelorama.

### 🖼️ Way 2 — Import any image as pixel art
Already have a reference image (AI-generated or hand-drawn)? Import it directly:
```bash
node docs/examples/import_universal_asset.js
```
The importer auto-detects the background, strips it out, and streams the pixel-perfect asset into Pixelorama with full transparency.

---

## 🗂️ Where to Start

| You want to… | Go here |
|---|---|
| Install & connect to Claude/Cursor | [Getting Started Guide](docs/getting-started.md) |
| Run a JS drawing script manually | [Custom Scripts Guide](docs/getting-started.md#manual-scripts) |
| Import an existing image into Pixelorama | [Image Import Guide](docs/getting-started.md#image-import) |
| See all available tools | [Tool Reference](docs/tool-reference.md) |
| Build or fix the Pixelorama plugin | [Plugin Setup](docs/plugin-setup.md) |
| Write an AI agent that draws | [Agentic Drawing Playbook](AGENTIC_DRAWING_PLAYBOOK.md) |
| See worked examples | [docs/examples/](docs/examples/) |

---

## 🏗️ Architecture

```
AI Client (Claude / Cursor / any MCP client)
        │  MCP — JSON-RPC over stdio
        ▼
   pix-MCP Server  (TypeScript / Node.js)
        │  HTTP REST — localhost:7373
        ▼
   Pixelorama Bridge Plugin  (GDScript)
        │  ExtensionsApi v8
        ▼
   Pixelorama v1.1.10
```

---

## ⚡ Quick Start

### Prerequisites
- [Node.js](https://nodejs.org/) ≥ 18
- [Pixelorama](https://www.pixelorama.org/) v1.1.10

### 1. Install the MCP server
```bash
git clone https://github.com/abidoo22/Pixelorama-MCP.git
cd Pixelorama-MCP/mcp-server
npm install && npm run build
```

### 2. Install the Pixelorama plugin
1. Open Pixelorama → **Edit → Preferences → Extensions**
2. Click **Add Extension** and select `pixelorama-plugin/PixMcpBridge.pck`
3. Enable it and restart Pixelorama

### 3. Connect Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "pix-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/pix-MCP/mcp-server/dist/index.js"]
    }
  }
}
```

Then ask Claude: *"Create a 64×64 canvas and draw a shiny red apple with a drop shadow"*

---

## 🎮 Example Gallery

| Sprite | Method | Script |
|---|---|---|
| 🪙 Golden Coin | Drawn by AI agent | `docs/examples/draw_coin.js` |
| 🥔 Potato | Drawn by AI agent | `docs/examples/draw_potato.js` |
| 🍌 Banana | Drawn by AI agent | `docs/examples/draw_banana.js` |
| 🌲 Tree | Drawn by AI agent | `docs/examples/draw_tree.js` |
| 💪 Muscular Man | Imported from AI image | `docs/examples/import_universal_asset.js` |
| Any image | Imported from AI image | `docs/examples/import_universal_asset.js` |

---

## 📖 Documentation

- [Getting Started](docs/getting-started.md) — Setup, prerequisites, client integration, and image import
- [Tool Reference](docs/tool-reference.md) — All 35+ MCP tools with parameters and return formats
- [Plugin Setup](docs/plugin-setup.md) — Compiling the GDScript plugin, troubleshooting quarantine
- [Agentic Drawing Playbook](AGENTIC_DRAWING_PLAYBOOK.md) — Shading math, geometry recipes, and batch optimization for AI agents

---

## 🛠️ Development

```bash
cd mcp-server
npm install
npm run dev   # watch mode

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
```

---

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a PR.

## 📄 License

[MIT](LICENSE) — go wild.

## 🙏 Credits

- [Pixelorama](https://www.pixelorama.org/) by Orama Interactive
- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [abidoo22](https://github.com/abidoo22)
- **Source:** [abidoo22/Pixelorama-MCP](https://github.com/abidoo22/Pixelorama-MCP)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-abidoo22-pixelorama-mcp
- Seller: https://agentstack.voostack.com/s/abidoo22
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.