@raydeck/gamma-app-mcp

Gamma MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to generate Gamma presentations, documents, and social media posts using the Gamma.app API.

What is MCP?

The Model Context Protocol (MCP) allows AI assistants like Claude to interact with external tools and data sources. This server exposes Gamma's AI generation capabilities to any MCP-compatible client.

Features

• 🎨 Generate presentations, documents, and social media posts
• 🤖 AI-powered content generation with customizable options
• 🎭 Theme support for consistent branding
• 📝 Multiple text modes: generate, condense, or preserve
• 🖼️ Image generation options (AI-generated or Unsplash)
• 📊 Export as PDF or PPTX
• 🌍 Multi-language support

Prerequisites

• Node.js 18 or higher
• A Gamma.app account with API access
• Gamma API key (get one from Gamma.app API settings)

Installation & Usage

Production Mode (via NPM)

Once published to NPM, you can use the server directly with npx:

• Configure your MCP client (e.g., Claude Desktop) by adding to your config file:

  macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  Windows: %APPDATA%\Claude\claude_desktop_config.json

  {
    "mcpServers": {
      "gamma": {
        "command": "npx",
        "args": ["-y", "@raydeck/gamma-app-mcp"],
        "env": {
          "GAMMA_API_KEY": "your-gamma-api-key-here"
        }
      }
    }
  }
  

• Restart your MCP client to load the server

Local Development / Testing Mode

For testing and development before publishing:

• Clone/navigate to the repository:

  cd /path/to/gamma-mcp
  

• Install dependencies:

  npm install
  

• Build the project:

  npm run build
  

• Configure your MCP client with the local path:

  macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  Windows: %APPDATA%\Claude\claude_desktop_config.json

  {
    "mcpServers": {
      "gamma": {
        "command": "node",
        "args": ["/absolute/path/to/gamma-mcp/dist/index.js"],
        "env": {
          "GAMMA_API_KEY": "your-gamma-api-key-here"
        }
      }
    }
  }
  

  Alternative using npm link:

  # In the gamma-mcp directory
  npm link
  
  # Then in your MCP config:
  {
    "mcpServers": {
      "gamma": {
        "command": "gamma-mcp",
        "env": {
          "GAMMA_API_KEY": "your-gamma-api-key-here"
        }
      }
    }
  }
  

• Restart your MCP client

Development Mode (with auto-reload)

For active development with TypeScript hot-reloading:

npm run dev

This runs the server directly from TypeScript source using tsx.

Configuration

Environment Variables

• GAMMA_API_KEY (required): Your Gamma API key

Available Tools

generate_gamma

Generate AI-powered Gamma content (presentations, documents, or social posts).

Note: This tool returns a generation ID. Use the get_gamma_generation tool to automatically wait for completion and retrieve the final URLs.

Parameters

Parameter	Type	Required	Description
inputText	string	✅	The text content to generate from (1-400,000 characters). Can be a short prompt, messy notes, or polished content.
textMode	string	❌	How to process input: generate, condense, or preserve (default: generate)
format	string	❌	Output format: presentation, document, or social (default: presentation)
themeName	string	❌	Name of a specific theme to use. Only use if the user explicitly requests a custom theme by name. Theme must exist in your Gamma workspace. Omit this parameter to use Gamma's default theme selection.
numCards	number	❌	Number of cards/slides to generate (1-60 for Pro, 1-75 for Ultra, default: 10)
cardSplit	string	❌	How to split content: auto or inputTextBreaks (default: auto)
additionalInstructions	string	❌	Additional instructions for content and layout (1-500 characters)
exportAs	string	❌	Export format: pdf or pptx

Text Options

Parameter	Type	Description
textOptions.amount	string	Amount of text per card: brief, medium, detailed, or extensive
textOptions.tone	string	Tone of voice for the content
textOptions.audience	string	Intended audience
textOptions.language	string	Output language code (e.g., 'en', 'es', 'fr')

Image Options

Parameter	Type	Description
imageOptions.source	string	Image source: aiGenerated or unsplash
imageOptions.model	string	AI model to use for image generation
imageOptions.style	string	Artistic style for generated images

Card Options

Parameter	Type	Description
cardOptions.dimensions	string	Card dimensions: fluid, 16x9, or 4x3

Sharing Options

Parameter	Type	Description
sharingOptions.workspaceAccess	string	Workspace access level

Example Usage

When using with Claude or another MCP client:

Create a 10-slide presentation about "The Future of AI" with a professional tone, 
targeted at business executives, using medium text amount and AI-generated images.

The AI will use the tool like this:

{
  "inputText": "The Future of AI - covering trends, opportunities, and challenges",
  "format": "presentation",
  "numCards": 10,
  "textOptions": {
    "amount": "medium",
    "tone": "professional",
    "audience": "business executives"
  },
  "imageOptions": {
    "source": "aiGenerated"
  }
}

get_gamma_generation

Retrieve the status and URLs of a Gamma generation. Automatically polls every 5 seconds until generation is complete (recommended by Gamma API).

Parameters

Parameter	Type	Required	Description
generationId	string	✅	The generation ID returned from generate_gamma
pollUntilComplete	boolean	❌	Whether to automatically poll until complete (default: true)
maxWaitSeconds	number	❌	Maximum wait time in seconds when polling (default: 300 = 5 minutes)

Automatic Polling (Default Behavior)

By default, the tool automatically polls every 5 seconds until the generation is complete or fails:

• ✅ Follows Gamma API recommendation (5-second intervals)
• ✅ Returns final URLs when ready
• ✅ Times out after 5 minutes (configurable)
• ✅ Simple single tool call - no manual polling needed

Response

The tool returns a JSON response containing:

• Status: pending, processing, completed, or failed
• URL: Link to the generated Gamma (editable in Gamma app)
• Export URLs: PDF or PPTX download links (if requested during generation)

Example Usage

Automatic polling (recommended):

{
  "generationId": "abc123"
}

Waits until complete and returns final URLs

Custom timeout:

{
  "generationId": "abc123",
  "maxWaitSeconds": 600
}

Waits up to 10 minutes

Single status check (no polling):

{
  "generationId": "abc123",
  "pollUntilComplete": false
}

Returns current status immediately without waiting

Response Format

generate_gamma Response

Returns a JSON response from the Gamma API containing:

• Generation ID (use with get_gamma_generation)
• Initial status

get_gamma_generation Response

Returns:

• Current status (pending, processing, completed, failed)
• Gamma URL (when completed)
• Export links for PDF/PPTX (if requested)

Development Workflow

Project Structure

gamma-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # NPM package configuration (includes mcpName for registry validation)
├── server.json           # MCP registry metadata
├── tsconfig.json
└── README.md

Note: The server.json file is required for publishing to the MCP Registry. It contains metadata about your server including its namespace (io.github.statechangelabs/gamma-app-mcp), package information, and deployment configuration.

Building

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Validating server.json

Before publishing to the MCP registry, you can validate your server.json:

npm run validate

This checks that your server.json has all required fields and is properly structured for the MCP registry.

Testing Locally

• Make changes to src/index.ts
• Run npm run build to compile
• Restart your MCP client to reload the server
• Test with your AI assistant

Publishing to NPM

When ready to publish:

• Update version in package.json and server.json:

  npm version patch  # or minor, or major
  

  Then update the version field in server.json to match.

• Build the project:

  npm run build
  

• Publish to NPM:

  npm publish --access public
  

• Users can then install via:

  npx @raydeck/gamma-app-mcp
  

Publishing to the MCP Registry

After publishing to NPM, you can publish to the official MCP registry to make your server discoverable:

• Install the MCP Publisher CLI:

  # macOS/Linux with Homebrew
  brew install mcp-publisher
  
  # Or download pre-built binaries from:
  # https://github.com/modelcontextprotocol/registry/releases
  

• Authenticate with GitHub (for io.github.* namespaces):

  mcp-publisher login github
  

• Publish to the registry:

  mcp-publisher publish
  

• Verify publication:

  curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.statechangelabs/gamma-app-mcp"
  

For detailed instructions, see the official publishing guide.

Troubleshooting

Server not starting

• Verify GAMMA_API_KEY is set correctly in your MCP config
• Check that Node.js version is 18 or higher
• Ensure the path in your config is absolute and correct

API Errors

• Verify your Gamma API key is valid
• Check that you have sufficient API credits
• Review Gamma API documentation for parameter requirements

MCP Client Not Detecting Server

• Ensure the config JSON is valid (use a JSON validator)
• Restart your MCP client after config changes
• Check client logs for error messages

Resources

• Gamma.app API Documentation
• Model Context Protocol Documentation
• MCP TypeScript SDK

License

ISC

Author

Ray Deck

Support

For issues and questions:

• GitHub Issues: Create an issue
• Gamma API Support: Gamma Help Center