# gamma-app-mcp

<!-- mcp-name: io.github.cphoskins/gamma-app-mcp -->

MCP server for [Gamma.app](https://gamma.app) — generate presentations, documents, webpages, and social posts via the [Gamma Public API v1.0](https://developers.gamma.app). Full parameter surface including templates, folders, headers/footers, and email sharing.

## Features

- **Generate from text** — presentations, documents, webpages, and social posts with the full v1.0 parameter surface
- **Generate from template** — swap content into an existing Gamma template, preserving layout (ideal for batch variants)
- **Poll generation status** — async job tracking with share URL, export URL, and credit usage
- **List workspace themes** — discover real theme IDs (no more hardcoded fallbacks)
- **List workspace folders** — paginated folder discovery for output organization
- **Describe options** — local enum introspection so LLMs can look up valid values without trial and error
- **Structured error surfacing** — Gamma API error codes and payloads flow through instead of being swallowed
- **Input validation** — char limits, enum checks, and format/dimension compatibility verified before network calls

## Installation

```bash
pip install gamma-app-mcp
```

Or install from source:

```bash
git clone https://github.com/cphoskins/gamma-app-mcp.git
cd gamma-app-mcp
pip install -e .
```

## Configuration

### Get your API key

1. Log in to [Gamma.app](https://gamma.app)
2. Go to **Account Settings > API Keys** (`https://gamma.app/settings/api-keys`)
3. Generate a key

> API key access requires a **Pro, Ultra, Teams, or Business** plan.

### Claude Code

```bash
claude mcp add gamma -s user \
  -e GAMMA_API_KEY=sk-gamma-your-key-here \
  -- gamma-app-mcp
```

### Claude Desktop / other stdio hosts

Add to your client config:

```json
{
  "mcpServers": {
    "gamma": {
      "command": "gamma-app-mcp",
      "env": {
        "GAMMA_API_KEY": "sk-gamma-your-key-here"
      }
    }
  }
}
```

### Environment variables

| Variable | Required | Description |
|---|---|---|
| `GAMMA_API_KEY` | Yes | Your Gamma API key (Account Settings > API Keys) |
| `GAMMA_BASE_URL` | No | Override the public API base URL (default: `https://public-api.gamma.app`) |

## Tools

| Tool | Purpose |
|---|---|
| `gamma_generate` | Create a presentation, document, webpage, or social post from text. Full control over format, themes, images, headers/footers, folders, sharing, and export. |
| `gamma_generate_from_template` | Create a variant from an existing Gamma template (`gammaId`), swapping content while preserving layout. |
| `gamma_get_status` | Poll a generation job by `generationId` until status is `completed` or `failed`. Returns `gammaUrl`, `exportUrl`, and credit usage. |
| `gamma_list_themes` | List themes in the authenticated workspace (standard + custom, 50+ themes). Cursor-paginated with `query`/`limit`/`after` — matching `gamma_list_folders`. Surfaces errors instead of falling back to hardcoded defaults. |
| `gamma_list_folders` | List workspace folders the authenticated user is a member of, with query filter and cursor pagination. |
| `gamma_describe_options` | Local lookup of accepted enum values for API parameters — no network call. |

## Example workflow

### 1. Simple presentation

```python
# Via MCP:
gamma_generate(
    input_text="Q3 2026 board update — ARR, burn, hiring plan, risks.",
    format="presentation",
    num_cards=12,
    text_options={"amount": "detailed", "tone": "professional", "audience": "board members"},
    image_options={"source": "aiGenerated", "style": "clean editorial"},
    card_options={"dimensions": "16x9"},
    export_as="pdf",
)
# -> {"generationId": "abc123...", "status": "submitted"}

gamma_get_status("abc123...")
# -> {"status": "completed", "gammaUrl": "https://gamma.app/docs/...", "exportUrl": "...", "credits": {...}}
```

### 2. Template-based batch variant

```python
# Discover theme and folder IDs
gamma_list_themes()
gamma_list_folders(query="Investor")

# Generate from an existing 1-page template
gamma_generate_from_template(
    prompt="Personalized intro deck for Acme Corp, a manufacturing client in Dallas.",
    gamma_id="gamma_tpl_abc123",
    theme_id="theme_xyz",
    folder_ids=["fld_investor_decks"],
    export_as="pptx",
)
```

### 3. Branded deck with header/footer

```python
gamma_generate(
    input_text="...",
    format="presentation",
    card_options={
        "dimensions": "16x9",
        "headerFooter": {
            "topLeft": {"type": "image", "source": "themeLogo", "size": "sm"},
            "bottomRight": {"type": "cardNumber"},
            "bottomCenter": {"type": "text", "value": "Confidential"},
            "hideFromFirstCard": True,
        },
    },
    sharing_options={
        "workspaceAccess": "edit",
        "externalAccess": "view",
        "emailOptions": {
            "recipients": ["team@example.com"],
            "access": "comment",
        },
    },
)
```

## Development

```bash
git clone https://github.com/cphoskins/gamma-app-mcp.git
cd gamma-app-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

### Release

```bash
./release.sh 0.3.0
git add -A && git commit -m "Release v0.3.0"
git tag v0.3.0
git push origin main --tags
```

The `push --tags` triggers [.github/workflows/publish.yml](.github/workflows/publish.yml), which builds the sdist/wheel, publishes to PyPI via trusted publishing (OIDC, no stored tokens), and creates a GitHub release. See [PUBLISHING.md](PUBLISHING.md) for the one-time PyPI trusted publisher setup.

## API reference

See [GAMMA_API_REFERENCE.md](GAMMA_API_REFERENCE.md) for the full v1.0 endpoint and parameter inventory sourced from [developers.gamma.app](https://developers.gamma.app).

## License

MIT — see [LICENSE](LICENSE). Inspired by [CryptoJym/gamma-mcp-server](https://github.com/CryptoJym/gamma-mcp-server); ground-up Python rewrite with expanded coverage and corrected v1.0 endpoint paths.