maginary-mcp

# maginary-mcp

[![PyPI](https://img.shields.io/pypi/v/maginary-mcp)](https://pypi.org/project/maginary-mcp/) [![Python](https://img.shields.io/pypi/pyversions/maginary-mcp)](https://pypi.org/project/maginary-mcp/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![smithery badge](https://smithery.ai/badge/maginaryai/maginary-mcp)](https://smithery.ai/servers/maginaryai/maginary-mcp)

Model Context Protocol server for [Maginary](https://maginary.ai) — an abstracted OpenRouter for images and video: ~20 model families (GPT-image-2, Seedance 2, Sora 2, Nano Banana Pro, Flux…) behind one Midjourney-style `--flag` prompt. 16 tools: full flag catalog, generate / upscale / vary / animate, in-chat signup, billing, and x402 pay-per-use for agents with a wallet.

<!-- mcp-name: io.github.maginaryai/maginary-mcp -->
<!-- The line above is how the official MCP Registry verifies this PyPI package belongs to the server
     named in server.json. It must match server.json "name" exactly. Keep it in the README (= PyPI long description). -->

[**Watch the demo →**](https://vimeo.com/1226724272)

## why

Maginary uses a Midjourney-style `--flag` prompt DSL over an async HTTP API. This server:

- surfaces the full parameter catalog to your LLM so it can pick the right flags
- offers a one-shot `generate` tool that hits `POST /api/gens/`
- offers `get_generation` + `wait_for_generation` for polling to a terminal state
- works offline for the catalog tools (ships a bundled snapshot; refreshed from the live docs endpoint at startup when reachable)

## connect

This is an MCP server — you don't run it directly; your AI client (Claude Desktop, Cursor, etc.) launches and talks to it behind the scenes. Just add one config block and start chatting.

### Claude Desktop

In Claude Desktop: settings → developer → edit config. That opens `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`). Add:

```json
{
  "mcpServers": {
    "maginary": {
      "command": "uvx",
      "args": ["--upgrade", "maginary-mcp"]
    }
  }
}
```

Restart Claude Desktop. Ask it to generate an image — it will see Maginary's tools automatically.

**No account yet?** No problem — Claude will walk you through signup (just give it your email). Already have an API key? Add it to skip that step:

```json
"env": { "MAGINARY_API_KEY": "sk-mag-…" }
```

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). Alternatively: `pip install maginary-mcp`.

## configuration

Nothing is required. For the stdio server you'll at most set one variable:

| var | default | meaning |
|---|---|---|
| `MAGINARY_API_KEY` | — | Bearer token from [app.maginary.ai/dashboard#api-keys](https://app.maginary.ai/dashboard#api-keys). Skips the in-chat signup flow. Catalog tools work without it. |
| `MAGINARY_BASE_URL` | `https://app.maginary.ai/api` | Override for staging or self-hosted. |
| `MAGINARY_MCP_LOG_LEVEL` | `INFO` | Standard Python log level; goes to stderr (stdout is reserved for MCP JSON-RPC). |

The rest only apply when you run the hosted server yourself (`maginary-mcp-http`, see below). Directory pages that scan the code list them too; ignore them for local use.

| var (hosted only) | default | meaning |
|---|---|---|
| `MAGINARY_MCP_HOST` / `MAGINARY_MCP_PORT` | `0.0.0.0` / `8642` | Bind address of the HTTP server. |
| `MAGINARY_PUBLIC_HOST` | `app.maginary.ai` | Sent to the backend as `X-Forwarded-Host` (with `-Proto`/`-For`) when `MAGINARY_BASE_URL` is an internal address, so the backend builds public URLs. |
| `MAGINARY_MCP_REQUIRE_AUTH` | off | On: every `/mcp` call needs a Bearer (OAuth token or API key); without one the server answers 401 + `WWW-Authenticate` pointing at `/.well-known/oauth-protected-resource`, which is how Claude/ChatGPT start the login. Trade-off: a wallet-only agent has no Bearer to send, so with the gate on it must make its first x402 payment over plain HTTP (`POST /api/gens/`) and then connect with a key from `POST /api/auth/wallet-account/`; the 401 body says so. |
| `MAGINARY_OAUTH_ISSUER` | `https://app.maginary.ai/o` | The authorization server named in the protected-resource metadata (the backend, django-oauth-toolkit). |
| `MAGINARY_MCP_RESOURCE_URL` | `https://mcp.maginary.ai/mcp` | This server's canonical resource identifier (RFC 8707 audience). Also what `/.well-known/mcp/server-card.json` advertises. |

## hosted (no-install) — Streamable HTTP

Connect a client straight to the hosted server at `https://mcp.maginary.ai/mcp`.
Zero install — the server is multi-tenant, so each request is scoped to
whatever credential it arrives with. Two ways to authenticate, pick whichever
fits the client:

**Connect (OAuth)** — for Claude Desktop, claude.ai, and any other client that
speaks MCP's OAuth spec. Add the server with no headers at all:

```json
{
  "mcpServers": {
    "maginary": { "url": "https://mcp.maginary.ai/mcp" }
  }
}
```

Click "Connect" in the client. It opens a login page on `app.maginary.ai`,
you sign in and approve the requested scopes, and the client holds the token
from then on — no key to generate or paste. Requires the server to be running
with `MAGINARY_MCP_REQUIRE_AUTH=1`; without it, no login is asked for at all.

**API key** — for any client that doesn't do the OAuth dance (or if you'd
rather not click through a login), generate a key at
[app.maginary.ai/dashboard#api-keys](https://app.maginary.ai/dashboard#api-keys)
and send it yourself:

```json
{
  "mcpServers": {
    "maginary": {
      "url": "https://mcp.maginary.ai/mcp",
      "headers": { "Authorization": "Bearer sk-mag-…" }
    }
  }
}
```

Both are equivalent once connected — same tools, same account. Catalog tools
work with no credential either way; `generate` / `get_generation` /
`wait_for_generation` need one. Run the hosted server yourself with:

### paying inside the tool call (x402 over MCP)

No key at all? Call `generate` anyway. Out of credits (or no account), the
result is `isError: true` with the x402 PaymentRequired at the top level
(`accepts`, `resource`, …) plus `error: "payment_required"`. An x402-capable
MCP client — the x402 SDK's `x402MCPSession` — signs `accepts[0]` and calls
the same tool again with the payment in `_meta["x402/payment"]`. The server
forwards it to the backend as `PAYMENT-SIGNATURE`; the backend verifies,
settles on Base and, for a wallet with no account, creates one. The settled
result carries the on-chain receipt in `_meta["x402/payment-response"]` and
`x402_receipt`. No API key is returned — subsequent requests use wallet-signed
auth headers (`X-Wallet-Address`, `X-Wallet-Signature`, `X-Wallet-Timestamp`)
instead.
The server holds no payment logic; everything is decided by the backend's
`/api/gens/` contract.

### wallet-signed authentication

After the first x402 payment creates the wallet's account, all subsequent
requests are authenticated by signing a short message with the wallet's
private key. Three headers on every request:

| Header | Value |
|---|---|
| `X-Wallet-Address` | Lowercased 0x EVM address (42 chars) |
| `X-Wallet-Signature` | EIP-191 `personal_sign` hex over the challenge string |
| `X-Wallet-Timestamp` | Unix seconds (integer) |

The challenge string is:

```
Maginary: authenticate <address> at <timestamp>. This does not move funds.
```

with `<address>` lowercased and `<timestamp>` the same unix seconds sent in
the header. The timestamp must be within 5 minutes of the server's clock
(30 s of future skew tolerated). No API key management needed — the wallet
*is* the credential.

```bash
pip install "maginary-mcp[http]"
maginary-mcp-http          # serves /mcp on 0.0.0.0:8642 (MAGINARY_MCP_PORT to change)
# — or —
docker build -t maginary-mcp . && docker run -p 8642:8642 maginary-mcp
```

The hosted server sets **no** `MAGINARY_API_KEY` (keys come per-request). It also
serves `/health`, a human page at `GET /`, the OAuth protected-resource metadata
and an MCP server card at `/.well-known/mcp/server-card.json` (live tool list,
auth posture) for directories that scan a bare URL.

## Claude Skill

The server ships an [Agent Skill](https://docs.claude.com/en/docs/agents/skills) that
teaches the `--flag` DSL, model selection, and the async generate→poll flow:

```bash
maginary-mcp --install-skill   # -> ~/.claude/skills/maginary-image-gen/SKILL.md
```

The skill stands on its own — hosts without MCP get the DSL plus the raw REST
calls (`POST /gens/` → poll). With the server connected, Claude instead calls
`search_parameters` for the authoritative flag list and `generate`/`wait_for_generation`
natively. Re-running updates it; local edits are protected unless you pass `--force`.
Source: [`src/maginary_mcp/SKILL.md`](src/maginary_mcp/SKILL.md).

## tools

### catalog (no auth)

- **`list_parameters(category?, status?, include_reserved=false)`** — enumerate the catalog
- **`search_parameters(query, category?, include_reserved=false)`** — text search over names / aliases / desc / examples
- **`get_parameter(name)`** — full record for one flag (canonical name or alias)

`list_parameters` responses include the `categories` / `statuses` taxonomy, and both
list/search responses carry `source` (`live` vs `bundled-snapshot`).

### generation (auth required)

- **`generate(prompt, callback_url?)`** — `POST /api/gens/`. Supports img2img: place image URLs in the prompt. Multiple URLs = multi-input compositing. Use `--sref <url>` for style-only transfer (not img2img).
- **`upload_image(file_path, filename?)`** — reads a local image file and uploads via `POST /api/images/upload/`. Returns a CDN URL for use in img2img prompts or `--sref`. Stdio connections only (hosted: use a URL directly or the REST endpoint).
- **`execute_action(generation_uuid, action_type, parent_image_index?, prompt?, callback_url?)`** — `POST /api/gens/{uuid}/actions/`. Run a follow-up on a completed generation's image (upscale, vary, pan, zoom, img2vid, reroll).
- **`get_gen