Metadata-Version: 2.5
Name: pixelmagic-mcp
Version: 0.4.0
Summary: MCP server for the PixelMagic image toolkit — generate, edit, upscale, remove background/object, layers, localize, enhance and vectorize, for agents like Claude and Cursor.
Project-URL: Homepage, https://pixelmagic.studio
Project-URL: Documentation, https://pixelmagic.studio/llms.txt
Author: PixelMagic
License: MIT
Keywords: ai,image,mcp,model-context-protocol,pixelmagic
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]<3,>=1.2.0
Description-Content-Type: text/markdown

# PixelMagic MCP server

Exposes the PixelMagic image toolkit as tools for AI agents (Claude Desktop, Cursor, and
any MCP client). Each tool calls the public REST API at `PIXELMAGIC_API_URL/api/v1/*` with
your API key, so it inherits the same auth, per-plan rate limiting, credit metering, and
SSRF protection — there is no separate, less-guarded path.

**Tools:** `generate`, `edit`, `upscale`, `remove_background`, `remove_object`, `layers`,
`localize`, `enhance`, `vectorize`, `list_models`, `account`, `health`. Works with MCP Python
SDK v1 and v2.

## Get an API key

Sign in at [pixelmagic.studio](https://pixelmagic.studio) → **Dashboard → API keys → Create
key**. Copy it (shown once). It looks like `sk_live_…`.

## Install & connect

You don't need to clone anything — [`uv`](https://docs.astral.sh/uv/) (or `pipx`) can run it
on demand. Add this to your client's MCP config:

**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pixelmagic": {
      "command": "uvx",
      "args": ["pixelmagic-mcp"],
      "env": { "PIXELMAGIC_API_KEY": "sk_live_..." }
    }
  }
}
```

Restart the client and the PixelMagic tools appear. Prefer a global install? Run
`pipx install pixelmagic-mcp` and use `"command": "pixelmagic-mcp"` (drop the `args`).

## Run from source

```bash
pip install "mcp[cli]>=1.2" httpx
export PIXELMAGIC_API_KEY=sk_live_...
python lucida_mcp.py                       # stdio
```

## Host it for your users (no install on their side)

```bash
MCP_TRANSPORT=streamable-http pixelmagic-mcp
```

Run it on any always-on host (a small VM, Render, Fly, Railway, a container — not Vercel's
serverless). Each user connects with their own `PIXELMAGIC_API_KEY`.

## Environment

| Variable | Default | Purpose |
| --- | --- | --- |
| `PIXELMAGIC_API_KEY` | — | Your `sk_live_…` key (required) |
| `PIXELMAGIC_API_URL` | `https://pixelmagic.studio` | API base URL |
| `MCP_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |

## Offline rendering (HyperFrames video renders)

`hyperframes_modal.py` renders each video in a Modal Sandbox with **no network**
(`block_network=True`). Before the Sandbox starts, the trusted function downloads the
composition's allowlisted assets — the GSAP CDNs (same list as `lib/video/ai-html-guard.ts`),
Google Fonts (CSS + font files), and user media on R2 (`*.r2.cloudflarestorage.com`,
`*.r2.dev`, `R2_PUBLIC_HOST`, and `pixelmagic.studio/api/asset` for the render owner's own
files) — via `safe_download.py` (60 MB per file, 600 MB total, 20 s each), writes them into
the Sandbox as `/tmp/proj/assets/<sha1>.<ext>` and rewrites the HTML to those relative paths
(`render_assets.py`). Any other URL is left as-is and simply fails offline.

- Kill switch: set `RENDER_OFFLINE=0` in the `pixelmagic-hyperframes` secret to go back to
  the old public-egress Sandbox (default is `1`), then redeploy.
- Tests: `python3 server/tests_render_assets.py`
- Redeploy after changing any of these files: `modal deploy server/hyperframes_modal.py`
