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

# @slidemaster/mcp-server

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.

## Quick Start

### 1. Get an API Key

Sign in to [SlideMaster](https://slidemaster.tw) and generate a key at **Settings > API Keys**.

### 2. Configure Claude Desktop

Add the following to your `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": "your-api-key-here"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

After saving the config, restart Claude Desktop. You should see the SlideMaster tools available in the tool picker.

## Local Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run the server (stdio transport)
SLIDEMASTER_API_KEY=your-key npm start
```

## Environment Variables

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

## Tools (20 total)

### Content Creation

| Tool | Method | Endpoint | Description |
|---|---|---|---|
| `generate_outline` | POST | `/outlines/generate` | Generate a presentation outline from a topic |
| `create_project` | POST | `/projects` | Create a new project |
| `upload_init` | POST | `/upload/init` | Initialize a file upload session (PPTX/PDF) |
| `upload_complete` | POST | `/upload/complete` | Mark an upload as complete |
| `render_slides` | POST | `/slides/render` | Render AI-generated slide images |

### Content Processing

| Tool | Method | Endpoint | Description |
|---|---|---|---|
| `generate_script` | POST | `/scripts/generate` | Generate a narration script for one slide |
| `batch_generate_scripts` | POST | `/scripts/batch-generate` | Generate scripts for all slides in a project |
| `generate_tts` | POST | `/tts/generate` | Generate text-to-speech audio |
| `generate_video` | POST | `/video/generate` | Compile the final video |

### Management

| Tool | Method | Endpoint | Description |
|---|---|---|---|
| `list_projects` | GET | `/projects` | List all projects (paginated) |
| `get_project` | GET | `/projects/{id}` | Get project details |
| `update_project` | PATCH | `/projects/{id}` | Update project properties |
| `delete_project` | DELETE | `/projects/{id}` | Delete a project |
| `list_slides` | GET | `/projects/{id}/slides` | List slides in a project |
| `update_slide` | PATCH | `/slides/{id}` | Update a slide's title or script |
| `delete_slide` | DELETE | `/slides/{id}` | Delete a slide |

### Query & Export

| Tool | Method | Endpoint | Description |
|---|---|---|---|
| `check_status` | GET | `/projects/{id}/status` | Check project processing status |
| `export_project` | GET | `/projects/{id}/export` | Export project with download URLs |
| `list_voices` | GET | `/voices` | List available TTS voices |

### Automation

| Tool | Method | Endpoint | Description |
|---|---|---|---|
| `topic_to_video` | POST | `/pipelines/topic-to-video` | End-to-end: topic to finished video |

## Example Conversation

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

Claude: I'll create that presentation for you using SlideMaster.

[Calls generate_outline with topic="renewable energy in Taiwan", slides_count=5]

Here's the outline I generated:
1. Taiwan's Energy Landscape
2. Solar Power Expansion
3. Offshore Wind Development
4. Government Policy & Targets
5. Future Outlook

Let me now create the project and render the slides.

[Calls create_project with title="Renewable Energy in Taiwan"]
[Calls render_slides with the outline data]
[Calls batch_generate_scripts]
[Calls generate_tts]
[Calls generate_video]

Your video is being generated! Let me check the status.

[Calls check_status]

The video is ready! Here are your download links:

[Calls export_project]

- Video: https://...
- Slides: https://...
```

Alternatively, use the one-shot pipeline:

```
User: Make me a video about machine learning basics

Claude: I'll use the topic-to-video pipeline to handle everything in one step.

[Calls topic_to_video with topic="machine learning basics"]
[Polls check_status until complete]
[Calls export_project for download links]

Your video is ready!
```

## API Documentation

Full API documentation is available at [https://slidemaster.tw/api-docs](https://slidemaster.tw/api-docs).

## License

MIT