# My Video Gift — MCP server

[![smithery badge](https://smithery.ai/badge/cryptolibertus/myvideogift)](https://smithery.ai/servers/cryptolibertus/myvideogift)

Create and deliver **personalized video gifts** (photos + an original song) from
any [Model Context Protocol](https://modelcontextprotocol.io) client — Claude
Desktop, Cursor, agent frameworks, IDEs.

It wraps the [My Video Gift agent API](https://developers.myvideogift.com). Renders
draw from a **prepaid credit balance**, so the connecting key must be a live key
with credits.

## Tools

| Tool | What it does | API |
|---|---|---|
| `list_occasions` | List supported occasions (drives song + tone) | `GET /occasions` |
| `check_account` | Key status + prepaid credit balance | `GET /account` |
| `create_gift` | Create a gift from photos + song, optionally render it | `POST /gifts` → `/photos` → `/render` |
| `get_gift` | Fetch a gift + (once ready) the film URL | `GET /gifts/{id}` |
| `list_gifts` | List your gifts, newest first (filter by status) | `GET /gifts` |

`create_gift` **will not render** unless you pass `consent=true` (you attest you
hold the rights to the photos and the recipient's depiction) and at least one
`photo_urls` entry — the guard runs *before* any credit is spent.

## Configuration

| Env var | Required | Default |
|---|---|---|
| `MVG_API_KEY` | yes | — (a `mvg_live_…` key from developers.myvideogift.com) |
| `MVG_API_BASE` | no | `https://myvideogift.com/api/v1` |

## Install (Claude Desktop, Cursor, …)

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "myvideogift": {
      "command": "npx",
      "args": ["-y", "myvideogift-mcp"],
      "env": { "MVG_API_KEY": "mvg_live_your_key_here" }
    }
  }
}
```

## Install (Claude Code plugin)

This repo is also a [Claude Code plugin](https://code.claude.com/docs/en/plugins):
the MCP server above plus a `create-video-gift` skill that walks the agent
through the account check → occasion → photos → consent → render flow.

From the community marketplace (once listed):

```
/plugin marketplace add anthropics/claude-plugins-community
/plugin install myvideogift@claude-community
```

Or straight from a local checkout:

```bash
claude --plugin-dir .
```

Enabling the plugin prompts for your `mvg_live_…` API key (stored in the OS
keychain, not in settings files) and passes it to the server as `MVG_API_KEY`.

## Local dev

```bash
npm install
npm run build
npm test        # offline smoke test — boots the server, asserts the tools
MVG_API_KEY=mvg_live_… npm start
```

## Publishing / listing (needs a human account)

- **npm**: `npm publish` (public) so `npx myvideogift-mcp` resolves.
- **Official MCP registry** — published as `io.github.CryptoLibertus/myvideogift`.
- **Smithery**: connect this repo at https://smithery.ai (uses `smithery.yaml`).
- **Glama**: auto-indexes public GitHub MCP servers.
- **mcp.so / PulseMCP**: submit this repo's URL via their site.