npm package: @slidemaster/mcp-server
Description: MCP server for SlideMaster - create AI presentation videos from Claude Desktop
Latest version: 1.10.1

<!-- mcp-name: io.github.Headdao/slidemaster-mcp -->

# @slidemaster/mcp-server

[![smithery badge](https://smithery.ai/badge/slidemaster/mcp)](https://smithery.ai/servers/slidemaster/mcp)

MCP (Model Context Protocol) Server for the [SlideMaster](https://slidemaster.tw) Public API. This server exposes 20+ tools that let any MCP-compatible AI assistant create AI-powered presentation videos from a simple topic.

## 5-Minute Quick Start

### Step 1: Get an API Key

1. Go to [slidemaster.tw](https://slidemaster.tw) and sign in with Google
2. Click your avatar (top right) → **Settings**
3. Navigate to **API Keys**
4. Click **Generate Key** — copy the `sm_live_...` key

### Step 2: Configure Your AI Client

**Claude Desktop** — add to `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "slidemaster": {
      "command": "npx",
      "args": ["-y", "@slidemaster/mcp-server"],
      "env": {
        "SLIDEMASTER_API_KEY": "sm_live_your_key_here"
      }
    }
  }
}
```

### Step 3: Restart and Go

Restart your AI client. Then just say: **"Make a 5-slide presentation about [your topic]"**

## Workflow

```
"Make slides about machine learning"
         │
         ▼
┌─────────────────┐
│ generate_outline │ ← Generates outline + auto-creates project
│                  │   Returns: project_id, slides array
└────────┬────────┘
         ▼
┌─────────────────┐
│  render_slides   │ ← Generates AI images for each slide
│                  │   Costs: 140 credits/slide (2K)
│                  │   Poll check_status until status="parsed"
└────────┬────────┘
         ▼
┌───────────────────────┐
│ batch_generate_scripts │ ← Generates narration scripts (optional)
└────────┬──────────────┘
         ▼
┌─────────────────┐
│  generate_tts    │ ← Text-to-speech audio (optional)
│                  │   Costs: 16 credits/slide
└────────┬────────┘
         ▼
┌─────────────────┐
│ generate_video   │ ← Compile final MP4 (optional)
│                  │   Costs: 80 credits/project
│                  │   Poll check_status until status="video_completed"
└────────┬────────┘
         ▼
┌─────────────────┐
│  export_pdf      │ ← Download as PDF (pdf_url field)
│  export_pptx     │ ← Download as PPTX (pptx_url field)
│  export_project  │ ← Get all download URLs
└─────────────────┘
```

**Shortcut**: Use `topic_to_video` to run the entire pipeline in one call.

**Tip**: `generate_outline` automatically creates a project — you do NOT need to call `create_project` separately.

## Credits Reference

| Operation | Cost per unit |
|---|---|
| Render slide (1K) | 42 credits |
| Render slide (2K) | 140 credits |
| Render slide (4K) | 250 credits |
| TTS per slide | 16 credits |
| Video per project | 80 credits |

**Quick math**: 2,000 credits ≈ 14 slides at 2K (slides only). A full 25-slide course with video ≈ 3,980 credits.

Call `get_credit_balance` before large projects to check remaining credits.

## Status Values

When polling `check_status`, the `status` field means:

| Status | Meaning | Next step |
|---|---|---|
| `processing` | Slides are being rendered | Poll again in 5-10 seconds |
| `parsed` | Slides ready, check scripts/audio | Call `batch_generate_scripts` or `generate_tts` |
| `generating_video` | Video being compiled | Poll again in 5-10 seconds |
| `video_completed` | Video ready | Call `export_project` for download URLs |
| `video_failed` | Video generation failed | Call `generate_video` to retry |

## Style Images

To apply a visual style, use `analyze_style_image` with a **publicly accessible image URL** (e.g. Imgur, Cloudinary). Base64 is not supported. The returned `style_guide` object can be passed to `render_slides`.

## Tools (20+ total)

### Content Creation

| Tool | Description |
|---|---|
| `generate_outline` | Generate outline from topic. **Auto-creates project** — returns project_id |
| `create_project` | Create an empty project (usually not needed — use generate_outline) |
| `render_slides` | Generate AI slide images. Requires slides array with title + description |
| `analyze_style_image` | Analyze a style reference image (public URL required) |
| `upload_init` | Initialize PPTX/PDF file upload |
| `upload_complete` | Complete a file upload |

### Content Processing

| Tool | Description |
|---|---|
| `generate_script` | Generate narration script for one slide |
| `batch_generate_scripts` | Generate scripts for all slides at once |
| `generate_tts` | Generate text-to-speech audio |
| `generate_video` | Compile slides + audio into MP4 video |

### Management

| Tool | Description |
|---|---|
| `list_projects` | List all projects |
| `get_project` | Get project details |
| `update_project` | Update project settings (TTS voice, language, etc.) |
| `delete_project` | Permanently delete a project |
| `list_slides` | List slides in a project |
| `update_slide` | Edit slide title or script |
| `delete_slide` | Delete a slide |

### Export

| Tool | Description |
|---|---|
| `export_pdf` | Export as PDF. Returns `pdf_url` (signed download link) |
| `export_pptx` | Export as PPTX. Returns `pptx_url` (signed download link) |
| `export_project` | Get all download URLs (slides, audio, video) |
| `export_evercam` | Export as offline HTML5 package |
| `evercam_status` | Poll EverCam export progress |

### Utilities

| Tool | Description |
|---|---|
| `check_status` | Poll processing progress |
| `get_credit_balance` | Check remaining credits with cost breakdown |
| `get_project_context` | Full project snapshot in one call |
| `list_voices` | Browse available TTS voices |
| `topic_to_video` | One-click: topic → finished presentation/video |

## Example Conversation

```
User: Create a 5-slide presentation about renewable energy in Taiwan

Claude: I'll create that for you.

[Calls generate_outline with topic="renewable energy in Taiwan", slides_count=5]
→ Returns project_id and slides array

[Calls render_slides with the project_id and slides]
→ Rendering started, polling...

[Calls check_status — status: "parsed", all slides rendered]

[Calls export_pdf]
→ Returns pdf_url

Here's your presentation! Download the PDF: [link]
```

## Local Development

```bash
npm install
npm run build
SLIDEMASTER_API_KEY=your-key npm start
```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `SLIDEMASTER_API_KEY` | Yes | Your SlideMaster API key (`sm_live_...`) |
| `SLIDEMASTER_API_BASE` | No | Override API base URL (default: `https://api.slidemaster.tw/api/v1/public`) |

## API Documentation

Full API docs: [slidemaster.tw/api-docs](https://slidemaster.tw/api-docs)

## License

MIT