gamma-app-mcp

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

MCP server for Gamma.app — generate presentations, documents, webpages, and social posts via the Gamma Public API v1.0. 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

pip install gamma-app-mcp

Or install from source:

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
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

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:

{
  "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

# 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

# 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

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

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

./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, which builds the sdist/wheel, publishes to PyPI via trusted publishing (OIDC, no stored tokens), and creates a GitHub release. See PUBLISHING.md for the one-time PyPI trusted publisher setup.

API reference

See GAMMA_API_REFERENCE.md for the full v1.0 endpoint and parameter inventory sourced from developers.gamma.app.

License

MIT — see LICENSE. Inspired by CryptoJym/gamma-mcp-server; ground-up Python rewrite with expanded coverage and corrected v1.0 endpoint paths.