# Gamma MCP Server

MCP server for [Gamma.app](https://gamma.app) - AI-powered presentation, document, and website generation.

## Features

- **Generate from scratch** - Create presentations, documents, social posts, or webpages from text
- **Create from template** - Adapt existing Gamma templates with new content
- **List themes** - Browse available themes for styling
- **List folders** - Browse workspace folders for organization
- **Poll generation status** - Check when async generation completes

## Installation

```bash
npm install @purple-horizons/gamma-mcp
```

Or clone and build:

```bash
git clone https://github.com/Purple-Horizons/gamma-mcp.git
cd gamma-mcp
npm install
npm run build
```

## Configuration

### Environment Variable

Set your Gamma API key:

```bash
export GAMMA_API_KEY=sk-gamma-xxxxxxxx
```

Get your API key from [Gamma Account Settings](https://gamma.app/settings) (requires Pro, Ultra, Teams, or Business plan).

### Claude Desktop / OpenClaw

Add to your MCP config:

```json
{
  "mcpServers": {
    "gamma": {
      "command": "node",
      "args": ["/path/to/gamma-mcp/dist/index.js"],
      "env": {
        "GAMMA_API_KEY": "sk-gamma-xxxxxxxx"
      }
    }
  }
}
```

### mcporter

Add to `~/.config/mcporter/mcporter.json`:

```json
{
  "servers": {
    "gamma": {
      "command": "node",
      "args": ["/path/to/gamma-mcp/dist/index.js"],
      "env": {
        "GAMMA_API_KEY": "sk-gamma-xxxxxxxx"
      }
    }
  }
}
```

## Tools

### gamma_generate

Generate a new gamma from text input.

**Parameters:**
- `inputText` (required) - Content to generate from (text + image URLs)
- `textMode` (required) - `generate` | `condense` | `preserve`
- `format` - `presentation` | `document` | `social` | `webpage`
- `themeId` - Theme ID (from `gamma_list_themes`)
- `numCards` - Number of slides (1-60 for Pro, 1-75 for Ultra)
- `cardSplit` - `auto` | `inputTextBreaks`
- `additionalInstructions` - Extra generation guidance
- `folderIds` - Array of folder IDs to save to
- `exportAs` - `pdf` | `pptx`
- `textAmount` - `brief` | `medium` | `detailed` | `extensive`
- `textTone` - Tone description (e.g., "professional, inspiring")
- `textAudience` - Target audience
- `textLanguage` - Language code (default: "en")
- `imageSource` - `aiGenerated` | `pictographic` | `pexels` | `giphy` | `webAllImages` | `webFreeToUse` | `webFreeToUseCommercially` | `placeholder` | `noImages`
- `imageModel` - AI model for images (e.g., "flux-1-pro", "imagen-4-pro")
- `imageStyle` - Image style description
- `dimensions` - Card dimensions (format-dependent)

**Returns:** `{ generationId: "..." }`

### gamma_get_generation

Check generation status.

**Parameters:**
- `generationId` (required) - ID from gamma_generate

**Returns:**
```json
{
  "status": "pending" | "completed",
  "generationId": "...",
  "gammaUrl": "https://gamma.app/docs/...",
  "credits": { "deducted": 150, "remaining": 3000 }
}
```

### gamma_create_from_template

Create a gamma based on an existing template.

**Parameters:**
- `gammaId` (required) - Template gamma ID
- `prompt` (required) - Instructions and content
- `themeId` - Override theme
- `folderIds` - Destination folders
- `exportAs` - `pdf` | `pptx`
- `imageModel` - AI model for new images
- `imageStyle` - Style for new images

**Returns:** `{ generationId: "..." }`

### gamma_list_themes

List available themes.

**Parameters:**
- `query` - Search by name
- `limit` - Max results (default 50)
- `after` - Pagination cursor

**Returns:**
```json
{
  "data": [{ "id": "...", "name": "...", "type": "standard|custom" }],
  "hasMore": false,
  "nextCursor": null
}
```

### gamma_list_folders

List workspace folders.

**Parameters:**
- `query` - Search by name
- `limit` - Max results (default 50)
- `after` - Pagination cursor

**Returns:**
```json
{
  "data": [{ "id": "...", "name": "..." }],
  "hasMore": false,
  "nextCursor": null
}
```

## Usage Example

```javascript
// 1. Generate a presentation
const gen = await gamma_generate({
  inputText: "5 ways AI is transforming healthcare",
  textMode: "generate",
  format: "presentation",
  numCards: 10,
  imageSource: "aiGenerated",
  imageStyle: "modern, professional photography"
});

// 2. Poll for completion
let status;
do {
  await sleep(5000);
  status = await gamma_get_generation({ generationId: gen.generationId });
} while (status.status === "pending");

// 3. Use the result
console.log(status.gammaUrl); // https://gamma.app/docs/xxxxx
```

## Credits

Gamma uses a credit-based system:
- ~3-4 credits per card
- ~2-120 credits per image (depends on model)

Check your remaining credits in the generation response.

## License

MIT