
mcp server for maginary.ai (an image and video generator that'll read and blow your mind)
mcp server for maginary.ai (an image and video generator that'll read and blow your mind)
·
Model Context Protocol server for Maginary — 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.
Maginary uses a Midjourney-style --flag prompt DSL over an async HTTP API. This server:
generate tool that hits POST /api/gens/get_generation + wait_for_generation for polling to a terminal stateThis 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.
In Claude Desktop: settings → developer → edit config. That opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). Add:
{
"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:
"env": { "MAGINARY_API_KEY": "sk-mag-…" }Requires Python 3.10+ and uv. Alternatively: pip install maginary-mcp.
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. 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. |
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:
{
"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 and send it yourself:
{
"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:
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.
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.
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-mcpThe 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.
The server ships an Agent Skill that
teaches the --flag DSL, model selection, and the async generate→poll flow:
maginary-mcp --install-skill # -> ~/.claude/skills/maginary-image-gen/SKILL.mdThe 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.
list_parameters(category?, status?, include_reserved=false) — enumerate the catalogsearch_parameters(query, category?, include_reserved=false) — text search over names / aliases / desc / examplesget_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).
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_generation(uuid) — GET /api/gens/{uuid}/. Response includes processing_result.available_actions mapping slots to valid action types.wait_for_generation(uuid, timeout_s=45) — poll to done / failed; a timeout result means still running — call againInside an MCP-capable client, once configured:
"Search the maginary catalog for anything about aspect ratio."
The LLM calls search_parameters("aspect") and gets back the --ar entry with values, examples, and supported models.
"Now generate a cinematic portrait 16:9 with the flagship model."
The LLM calls generate("a cinematic portrait --ar 16:9 --flagship"), gets a uuid, then wait_for_generation(uuid) and reads image_urls[] out of the terminal record.
"Upscale the first image."
The LLM checks processing_result.available_actions["0"], sees "upscale_2x", calls execute_action(uuid, "upscale_2x", 0), gets a new uuid, then wait_for_generation(new_uuid).
"Edit this photo to look like a watercolor." (user provides a local image)
The LLM calls upload_image("/tmp/photo.png") → gets a CDN URL, then generate("https://cdn.maginary.ai/…/photo.webp reimagine as watercolor painting"). (stdio only — on hosted, the user provides a URL instead.)
https://maginary.ai/docs/parameters.json, 5-second timeout.src/maginary_mcp/parameters_snapshot.json used as a fallback whenever live fetch fails (no network, docs site down, etc.).python scripts/refresh_snapshot.py — deliberately not baked into the wheel build so a new snapshot always corresponds to a reviewed commit.The source field on list_parameters / search_parameters responses tells you which one is active.
cd mcp
python -m venv venv && source venv/bin/activate
pip install -e .
maginary-mcp # runs on stdio; kill with Ctrl+DMIT.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add maginary -- uvx --upgrade maginary-mcp{
"mcpServers": {
"maginary": {
"args": [
"--upgrade",
"maginary-mcp"
],
"command": "uvx"
}
}
}code --add-mcp '{"name":"maginary","args":["--upgrade","maginary-mcp"],"command":"uvx"}'[mcp_servers.maginary]
command = "uvx"
args = ["--upgrade", "maginary-mcp"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/maginary-mcp to learn what the "Maginary Mcp" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
pip install "maginary-mcp[http]"| Name | What it does |
|---|---|
list_parameters | List Maginary prompt-DSL parameters. Args: category: Restrict to one category (e.g. ``composition``, ``video``, ``model``, ``outpaint``). Call with no filters once — the respo |
search_parameters | Text-search over parameter names, aliases, descriptions, values, examples. Args: query: Substring match, case-insensitive. category: Optional single-category restriction. |
get_parameter | Return the full record for a single parameter (canonical name or alias). Args: name: Parameter name with or without leading ``--`` (e.g. ``ar``, ``--ar``, ``aspect``). Case-in |
generate | Kick off a generation via POST /api/gens/. Args: prompt: The user's words, passed through as-is. Do NOT add flags the user did not ask for — no ``--ar``, no ``--flagship``, no |
get_generation | Fetch a generation by UUID (GET /api/gens/{uuid}/). Args: uuid: The UUID returned by ``generate``. Returns: The full generation record. If terminal, ``image_urls[]`` holds th |
wait_for_generation | Poll ``get_generation`` on a backoff until it reaches done / failed. Args: uuid: The UUID returned by ``generate``. timeout_s: Return after this many seconds even if still running |
upload_image | Upload a local image and get a CDN URL for img2img or ``--sref``. Only available on local (stdio) connections. On hosted/remote connections, place an existing image URL directly in the promp |
execute_action | Run a follow-up action on a completed generation's image. After ``generate`` → ``wait_for_generation``, the response's ``processing_result.available_actions`` lists what's possible per slot. |
create_account | Create a new Maginary account for the given email address. Returns the auto-generated password — display it to the user ONCE so they can save it. A verification email is sent; the user must c |
create_wallet_account | Create (or access) a Maginary account using a wallet signature. Sign the message ``Maginary: authenticate <address> at <timestamp>. This does not move funds.`` with EIP-191 ``personal_sign`` |
check_account_status | Check account verification status, credit balance, and API key count. Use this after ``create_account`` to poll whether the user has clicked the verification link. Pass ``email`` + ``password |
manage_api_key | Create, list, or revoke Maginary API keys (up to 10 per account). Auth: pass ``email`` + ``password`` for Basic auth (onboarding), or omit both to use the configured API key (normal operation |
configure_api_key | Activate an API key. Local (stdio) servers persist it; hosted does not. Call this after ``manage_api_key(action='create')`` returns a ``raw_key``. On a local server the key is saved to ``~/.c |
get_products | List available Maginary products/plans with pricing. No authentication required. Use this to present purchase options to the user. The ``novice_pack`` ($10, 150 credits) is the recommended st |
checkout | Create a Stripe checkout session for purchasing a product. Returns a ``checkout_url`` — the user must open it in a browser to complete payment. After payment, credits are provisioned automati |
get_balance | Check remaining credits and uploads for the authenticated account. Args: email: Account email (for Basic auth). password: Account password (for Basic auth). Returns: |
Read live from the server on November 15, 2026.
Paste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/maginary-mcp)Nothing comparable is listed yet.
No tagged releases on record.
Connect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "maginary-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.