# Manic MCP Server

Give any MCP-capable AI — Claude Code, Claude Desktop, or a local model — the
ability to **write, validate, and render [Manic](https://maniclang.com)
animations**.

The connected model is the author: this server deliberately has no AI-
generation tool and spends no Manic AI credits. Instead it hands the model the
complete Manic authoring guide, then lets it validate its own `.manic` source
and render real videos through the Manic platform with your API key.

## Tools

| Tool | Auth | What it does |
|---|---|---|
| `manic_authoring_guide` | none | Fetches the full, current Manic language guide — the same system prompt Manic's own AI uses. The model reads this once, then writes real Manic. |
| `manic_check` | API key (`check`) | Validates `.manic` source and returns exact diagnostics. Cheap — always check before rendering. |
| `manic_render` | API key (`render:create`) | Submits source to the hosted renderer (mp4/gif/webm/mov/still). Returns a durable job id. Spends export credits. |
| `manic_render_status` | API key (`jobs:read`) | Polls a render job; returns the artifact URL when done, or the exact compile error to fix. |
| `manic_save_to_project` | API key (`projects:read/write`) | Saves the file into your Manic project, where it opens in Manic Create and Manic Workbench. |

The intended loop: **guide → write → check → (fix → check…) → render → poll →
video** — with every generated file optionally saved as a real project
document.

## Setup

Create an API key at [app.maniclang.com/account](https://app.maniclang.com/account)
with scopes: `check`, `render:create`, `jobs:read`, `projects:read`,
`projects:write`. (Without a key, only `manic_authoring_guide` works.)

No install needed — `npx` runs the published package directly.

### Claude Code

```sh
claude mcp add manic -e MANIC_API_KEY=mk_live_… -- npx -y @maniclang/mcp-server
```

### Claude Desktop / other MCP clients

```json
{
  "mcpServers": {
    "manic": {
      "command": "npx",
      "args": ["-y", "@maniclang/mcp-server"],
      "env": { "MANIC_API_KEY": "mk_live_…" }
    }
  }
}
```

### From source (development)

```sh
npm install && npm run build
```

Then use `node /path/to/manic-mcp-server/dist/index.js` as the command
instead of `npx -y @maniclang/mcp-server` in any config above.

### Other clients

Cursor, Windsurf, Cline, Continue, Zed, LM Studio, and any generic stdio MCP
client — see **[docs/USAGE.md](docs/USAGE.md)** for copy-paste configs, the
intended authoring loop, example prompts, the cost model, and troubleshooting.

### Configuration

| Variable | Default | Purpose |
|---|---|---|
| `MANIC_API_KEY` | — | Your Manic API key; required for everything except the authoring guide |
| `MANIC_API_BASE_URL` | `https://api.maniclang.com/v1` | Platform API base |
| `MANIC_SYSTEM_PROMPT_URL` | the hosted Manic guide | Override the authoring-guide source |

## Try it

Ask your model:

> "Read the Manic authoring guide, then create a 15-second animation of a
> pendulum tracing its path, validate it, render it as mp4, and give me the
> video link."

## Links

- [Manic](https://maniclang.com) · [Manic App](https://app.maniclang.com) · [API reference](https://docs.maniclang.com/api)
- [Manic Create](https://app.maniclang.com/create) — browser playground
- [Manic Workbench](https://github.com/maniclang-x/manic-workbench) — desktop client
- [Manic Animate](https://github.com/maniclang-x/manic-browser-extension) — browser extension