# ridvay-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/tom-tgr/ridvay-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ridvay-mcp

## Description
Create & edit Ridvay Studio posters, flyers & social designs — AI-generated or self-composed.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ridvay-mcp": {
    "command": "npx",
    "args": ["-y","ridvay-mcp"]
  }
}
```

## Documentation & README

<!-- Banner designed & rendered by this very MCP server (create_poster → export_poster). -->
![Ridvay MCP — design tools for AI agents](https://storage.googleapis.com/ridvay.appspot.com/public/system/0de9ade1-056d-447a-80b9-d89edcaad700.png)

# ridvay-mcp

MCP (Model Context Protocol) server that lets AI assistants — Claude Code, Claude Desktop,
GitHub Copilot (VS Code agent mode), Cursor, and any other MCP client — create and edit
**[Ridvay Studio](https://ridvay.com/studio)** posters, flyers, and social designs straight
from a chat conversation.

Every design comes back as a working share link (`ridvay.com/d/…`) plus links to open and
edit it in the Studio editor.


## Hosted endpoint (no install)

The same server runs at **https://mcp.ridvay.com** (streamable HTTP). Two ways to authenticate:

- **URL with your key** — for clients that add connectors by URL and cannot set headers (claude.ai custom connectors, ChatGPT connectors): `https://mcp.ridvay.com/mcp/sk-ridvay-…`. Treat that URL like the key itself; revoke it any time at ridvay.com/user/api-keys.
- **Bearer header** — for clients that support headers: `https://mcp.ridvay.com/mcp` with `Authorization: Bearer sk-ridvay-…`. Claude Code: `claude mcp add --transport http ridvay https://mcp.ridvay.com/mcp --header "Authorization: Bearer sk-ridvay-…"`.
- **Try it without an account** — `https://mcp.ridvay.com/mcp/demo` is a sandbox: no key, no sign-up, the free tools only (design guide, compose a design, render, export PNG, share). Designs made there are public and may be removed; it is rate-limited per network. Claude Code: `claude mcp add --transport http ridvay-demo https://mcp.ridvay.com/mcp/demo`.
- **Sign in (OAuth 2.1)** — for clients that support MCP OAuth (claude.ai custom connectors, ChatGPT connectors/plugins, Claude Code, Cursor, MCP Inspector): add `https://mcp.ridvay.com/mcp` with no key, and the client discovers `api.ridvay.com` as the authorization server, registers itself (Dynamic Client Registration) or presents a Client ID Metadata Document, and sends you to `ridvay.com/oauth/consent` to approve. The token it receives is a normal Ridvay API key named "<client> (OAuth)", so you can revoke it any time from your account page (or the client can call the revocation endpoint).

### Living designs tools (0.6.0)

`list_designs`, `share_design` (view / edit / live-image / screen links), `get_values` and `set_values`
(update a design's declared `{{variables}}` — a menu board or price board that refreshes itself on the
`/screen/<id>` page and the `/img/<id>.png` live image), and `list_brands` (pass `brand_id` to `generate_poster`).

## How it works

![You ask in plain language; your assistant composes the design; Ridvay renders it and hands back links](https://raw.githubusercontent.com/tom-tgr/ridvay-mcp/HEAD/assets/how-it-works.gif)

*Every frame of that GIF was designed and rendered by this MCP server* — a four-page design
composed as design IR, saved with `create_poster`, then exported page by page with
`export_poster`. No screen recording, no image editor.

## Tools

| Tool | What it does |
|------|--------------|
| `get_design_guide` | **Start here** — the design-IR authoring spec (element types, backgrounds, fonts, worked example) that teaches your assistant to compose designs itself. |
| `create_poster` | **The preferred path:** your assistant composes the design as Ridvay design IR — Ridvay only stores, renders, and shares it. Fast, free, full creative control. |
| `generate_poster` | Fallback: Ridvay's AI designs from a text brief (slower, consumes the account's generation credits). |
| `recreate_poster` | Turn an **existing design image** (poster photo, screenshot, export — file path or URL) into an editable design: text becomes editable, shapes become vectors, imagery is re-rendered fresh. Slow (1–4 min), uses generation credits. |
| `refine_poster` | Natural-language edit of an existing design (`design_id`, `instruction`). |
| `check_poster` | Report whether a design's AI images finished rendering and return its links + view count (`Views: N`). |
| `export_poster` | Render a design to a downloadable **PNG/JPEG** at its native pixel size (`scale` 1–4, default 2). |
| `animate_poster` | Add motion (entrance/exit, page transitions, morph) — blank for a tasteful default, or describe it. |
| `export_video` | Render an animated design to a downloadable **H.264 MP4** (optional looped soundtrack). |
| `check_export` | Poll an async `export_poster` / `export_video` job for its download URL. |

Your AI client is the designer; Ridvay is the save/render/share backend. Client-authored
designs may still include `prompt` image slots — Ridvay renders those server-side after
creation. `generate_poster` remains for when the assistant can't compose the design itself.

**Export & motion:** `export_poster` gives you the actual poster image at its real dimensions
(e.g. a 1080×1350 PNG), not the share page. For animation, either include motion fields when
you compose the design (see the guide) or call `animate_poster`, then `export_video` for an MP4.

`size` accepts `1080x1080` (default), `1080x1920` / `story`, `1080x1350`, `1920x1080`,
`a4`, `slide`, or any `WxH`.

### Live images

Every **shared** design also gets an always-current image URL — each fetch re-resolves the
design's live data bindings (`{{time.now}}`, countdowns, JSON feeds, declared `{{vars}}`),
so an embedded image never goes stale (re-rendered at most every 60 s):

```
https://ridvay.com/img/{designId}.png
```

Declared vars are filled from query params, which makes personalized email images a one-URL
job with your ESP's merge tags:

```
https://ridvay.com/img/abc123.png?name=*|FNAME|*
```

A `.jpg` variant plus `page`, `scale`, `w`, and `quality` params are supported — see
`get_design_guide` ("Live data bindings + live image URL") for the bindings format (including
the reserved param names that can't double as binding/var keys).

Every live-image load and every `/d/` share-page view counts toward the design's view
count — `check_poster` reports it as `Views: N`.

## Get an API key

Sign in and create a key at **[ridvay.com/user/api-keys](https://ridvay.com/user/api-keys)**.
Designs generated through MCP appear in your own *My designs*.

## Quickstart

**Claude Code**

```bash
claude mcp add --scope user ridvay --env RIDVAY_API_KEY=sk-ridvay-… -- npx -y ridvay-mcp
```

**Claude Desktop** — add to `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ridvay": {
      "command": "npx",
      "args": ["-y", "ridvay-mcp"],
      "env": { "RIDVAY_API_KEY": "sk-ridvay-…" }
    }
  }
}
```

**VS Code / GitHub Copilot agent mode** — add to your user `mcp.json`
(Command Palette → "MCP: Open User Configuration"), then enable **ridvay** in the
Copilot Chat tools picker:

```json
{
  "servers": {
    "ridvay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ridvay-mcp"],
      "env": { "RIDVAY_API_KEY": "sk-ridvay-…" }
    }
  }
}
```

Then ask your assistant things like:

> Generate a story-size poster for our weekend flash sale — 30% off everything, Saturday only.

## Examples

**A poster, straight from a brief**

> Generate a story-size poster for our weekend flash sale — 30% off everything, Saturday only.

**A promo video, end to end** — design, animation, and MP4 in one turn:

> Using the ridvay MCP, create a 3-page 1080x1920 promo video design about [topic]. Page 1: a
> bold hook. Page 2: three or four key points with accent bars. Page 3: a worked example plus a
> call to action. Dark navy background, blue accents, Poppins headlines. Then animate it with
> snappy staggered entrances and morph transitions, and render it to MP4.

**An existing design, made editable again**

> Recreate ~/Desktop/last-years-flyer.png as an editable design, then change the date to
> October 3rd and set the headline in our brand blue.

**An image that never goes stale** — live bindings resolve on every fetch:

> Build a 1080x1080 status card with today's date and a countdown to our September 1 launch,
> then give me the live image URL.

A longer walkthrough of the video example, with the agent's actual tool sequence, is on the
blog: **[Ridvay MCP: free AI design generation from Claude Code](https://ridvay.com/blog/ridvay-mcp)**.

## Environment

| Var | Required | Meaning |
|-----|----------|---------|
| `RIDVAY_API_KEY` | yes | Your Ridvay API key (`sk-ridvay-…`). |
| `RIDVAY_API_URL` | no | Default `https://api.ridvay.com`. |
| `RIDVAY_WEB_URL` | no | Base for returned links, default `https://ridvay.com`. |
| `RIDVAY_SUB_USER_ID` | no | Admin/platform keys only: act on behalf of a specific user. |

## Behavior notes

- **Sharing:** `generate_poster` / `create_poster` create an unlisted public share link by
  default so the chat reply contains a working `/d/{id}` URL. Pass `share: false` to keep
  a design private to your account (only the Studio edit link is returned).
- **Deferred images:** generation returns as soon as the layout is ready; AI/stock images
  render server-side in the background (~1 min). `check_poster` reports on and, if
  needed, re-triggers that pass.

## Telemetry

Content and usage data from the MCP (such as prompts and generated designs) may be used to
improve Ridvay's products, services, and AI features. Requests include basic attribution:
the connecting MCP client's name/version and, when the assistant provides the optional
`agent_model` argument, the model id that authored the design.

## Development

```bash
npm install
npm run build     # emits dist/
npm test          # vitest unit suite
node dist/index.js  # run the stdio server directly (needs RIDVAY_API_KEY)
```

MIT © Ridvay