# @retomagic/mcp

An [MCP](https://modelcontextprotocol.io) server for the **Magicly** image & video
generation API. Lets any MCP client (Claude Desktop, IDEs, agents) generate media
through your Magicly developer API key.

## Setup

1. Create an API key at **dev.magicly.ai → API Keys**.
2. Add the server to your MCP client. For Claude Desktop
   (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "magicly": {
      "command": "npx",
      "args": ["-y", "@retomagic/mcp"],
      "env": { "MAGICLY_API_KEY": "sk_live_..." }
    }
  }
}
```

Restart the client. That's it.

## Tools

- **`list_models`** — list available models with id, media type, price ($) and inputs.
- **`generate`** — generate an image/video: `{ model, prompt, aspect_ratio?, size?, seconds?, seed?, image? }`. Creates a prediction and waits for the result, returning the output URL(s). Pass `wait: false` to return immediately with an id to poll.
- **`get_prediction`** — fetch a prediction's status/output by `id`.

## Config

| Env | Default | Description |
| --- | --- | --- |
| `MAGICLY_API_KEY` | – | **Required.** Your developer API key (`sk_live_…`). |
| `MAGICLY_API_URL` | `https://api.magicly.ai/v1` | API base URL (override for staging). |

Billing is metered in credits (1000 credits = \$1) against your organization's
balance. See dev.magicly.ai for pricing, keys and usage.

## Development

```
npm install
npm run build        # → dist/
MAGICLY_API_KEY=sk_live_... npm start
```