Gamma MCP Server

This document guides you through setting up and running the Gamma MCP (Model Context Protocol) server, which allows you to generate presentations using the Gamma API directly from MCP clients like Anthropic's Claude for Desktop.

What is Gamma?

Gamma is an AI-powered platform designed to help users create various types of content, with a strong focus on presentations. It leverages artificial intelligence to automatically generate slides, suggest text, and incorporate imagery, allowing for rapid development of polished presentations from simple prompts or existing documents. This MCP server specifically interacts with Gamma's API to bring this presentation generation capability into environments like Claude for Desktop. Check out the Gamma API docs to learn more.

What We'll Be Building

This server exposes a tool to an MCP client (like Claude for Desktop) that can take a prompt and various parameters to generate a presentation using the Gamma API. The server will return a link to the generated presentation.

Core MCP Concepts

Model Context Protocol servers can provide three main types of capabilities:

• Resources: File-like data that can be read by clients (like API responses or file contents).
• Tools: Functions that can be called by the LLM (with user approval).
• Prompts: Pre-written templates that help users accomplish specific tasks.

This server primarily focuses on providing a Tool.

Prerequisite Knowledge

This quickstart assumes you have familiarity with:

• Node.js and TypeScript.
• LLMs like Anthropic's Claude.
• Basic command-line usage.

System Requirements

• Node.js (v16 or higher recommended).
• npm (Node Package Manager) or yarn.
• Access to the Gamma API. You'll need an API key, don't have one? Check out the Gamma API docs to get one.

Set Up Your Environment

1. Clone the Repository / Get the Code:

If this project is in a Git repository, clone it:

git clone git@github.com:gamma-app/gamma-mcp-server.git
    cd gamma-mcp-server

2. Initialize Your Node.js Project (if not cloned):

If you created a new directory, initialize a `package.json` file:

npm init -y

3. Install Dependencies:

You'll need the MCP SDK, Zod for validation, node-fetch for API calls, TypeScript, and ts-node to run TypeScript directly.

npm install @modelcontextprotocol/sdk zod node-fetch typescript ts-node @types/node
    # or
    # yarn add @modelcontextprotocol/sdk zod node-fetch typescript ts-node @types/node

4. Configure TypeScript:

You might want to adjust the `tsconfig.json` to suit your preferences, but the default should work. Ensure `moduleResolution` is set to `"node"` or `"node16"` / `"nodenext"` and `module` is compatible (e.g. `"commonjs"` if running with `ts-node` in a CommonJS context, or adjust for ES Modules). The provided `src/index.ts` uses ES module syntax (`import ... from`).

A common `tsconfig.json` for ES Modules with Node.js might include:

{
      "compilerOptions": {
        "target": "ES2020",
        "module": "ESNext",
        "moduleResolution": "node",
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "strict": true,
        "skipLibCheck": true,
        "outDir": "./dist" // Optional: if you plan to compile
      },
      "include": ["src/**/*"],
      "exclude": ["node_modules"]
    }

Also, in your `package.json`, add `"type": "module"` if you are using ES Modules.

5. API Key Configuration:

The server requires your Gamma API key. We use the `dotenv` package to load this key from a `.env` file in the project root.

1. Create a file named `.env` in the root of your project (e.g., alongside your `package.json`).

2. Add your Gamma API key to this file like so:

GAMMA_API_KEY="your_actual_gamma_api_key_here"

Replace `"your_actual_gamma_api_key_here"` with your actual key.

IMPORTANT: The `.env` file is included in the project's `.gitignore` file, so it WILL NOT be committed to your Git repository. This is crucial for keeping your API key secret. Do not remove `.env` from `.gitignore` or commit your API key directly into your codebase.

If the `GAMMA_API_KEY` is not found in the environment (e.g., if the `.env` file is missing or the key isn't set), the server will log a fatal error and exit upon starting.

Understanding the Server Code (`src/index.ts`)

Let's break down the key parts of the `src/index.ts` file:

1. Imports:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
    import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
    import { z } from "zod";
    import fetch from "node-fetch";

These lines import the necessary MCP server classes, Zod for schema definition and validation, and `node-fetch` for making HTTP requests.

2. Gamma API Configuration:

const GAMMA_API_URL = "https://api.gamma.app/public-api/v0.1/generate";
    const GAMMA_API_KEY = "YOUR_GAMMA_API_KEY_HERE"; // Replace or use env var

This sets up the base URL for the Gamma API and the API key.

3. `generatePresentation` Helper Function:

This `async` function is responsible for making the POST request to the Gamma API with the provided parameters and handling the response or errors.

4. MCP Server Instance:

const server = new McpServer({
      name: "gamma-presentation",
      version: "1.0.0",
      capabilities: {
        resources: {},
        tools: {},
      },
    });

This initializes a new MCP server with a name and version.

5. Tool Definition (`server.tool`):

server.tool(
      "generate-presentation",
      "Generate a presentation using the Gamma API...",
      {
        /* Zod schema for parameters */
      },
      async (params) => {
        /* Tool execution logic */
      }
    );

This is the core of the MCP server.

6. `main` Function:

async function main() {
      const transport = new StdioServerTransport();
      await server.connect(transport);
      console.error("Gamma MCP Server running on stdio");
    }

    main().catch(/* ... */);

This function sets up the server to communicate over standard input/output (stdio) and starts it.

Running Your Server

1. Set the `GAMMA_API_KEY` Environment Variable:

Before running the server, ensure you have set the `GAMMA_API_KEY` environment variable as described in the "API Key Configuration" section above.

2. Start the Server:

With the environment variable set, you can run the server using `ts-node`:

npx ts-node src/index.ts

Alternatively, you can add a script to your `package.json`:

// package.json
    "scripts": {
      "start": "ts-node src/index.ts",
      // if you compile to JS first:
      // "build": "tsc",
      // "start:prod": "node dist/index.js"
    },

Then run:

npm start
    # or
    # yarn start

If successful, you should see:

Gamma MCP Server running on stdio

The server is now running and waiting for an MCP client to connect via stdio.

Testing Your Server with Claude for Desktop

To use this server with Claude for Desktop, you need to configure Claude for Desktop to know how to launch your server.

1. Install Claude for Desktop:

Make sure you have Claude for Desktop installed. You can get it from the official source. Ensure it's updated to the latest version.

2. Locate Claude for Desktop Configuration File:

The configuration file is typically located at:

If the file or directories don't exist, create them.

3. Configure Your Server in `claude_desktop_config.json`:

Open `claude_desktop_config.json` in a text editor. Add your Gamma server to the `mcpServers` object.

Important: You need the absolute path to your project directory and to `ts-node` (or `node` if you compile to JS).

Here's an example configuration. You MUST replace `/ABSOLUTE/PATH/TO/YOUR/gamma-mcp-server` with the actual absolute path.

You will also need to ensure that the `GAMMA_API_KEY` environment variable is available to the process launched by Claude for Desktop. How to do this depends on your OS and how Claude for Desktop launches processes. Some common methods include:

A simple way for testing is often to ensure `GAMMA_API_KEY` is set in your user's global shell environment (e.g., in `~/.bashrc`, `~/.zshrc`, or system-wide environment variables on Windows) before launching Claude for Desktop.

{
      "mcpServers": {
        "gamma-presentation-generator": {
          "command": "npx", // Or absolute path to npx, or node
          "args": [
            "ts-node", // If command is 'npx'
            // If command is absolute path to node:
            // "/PATH/TO/gamma-mcp-server/node_modules/ts-node/dist/bin.js",
            "src/index.ts"
          ],
          "cwd": "/ABSOLUTE/PATH/TO/YOUR/gamma-mcp-server" // Current Working Directory for the server
        }
      }
    }

Explanation:

4. Save and Restart Claude for Desktop:

Save the `claude_desktop_config.json` file and completely restart Claude for Desktop.

5. Test with Commands:

Once Claude for Desktop restarts, it should attempt to connect to your server.

Claude should recognize the request, identify your tool, and (after your approval if configured) execute it. Your server (running in its own terminal or process) will then call the Gamma API, and the link to the presentation should appear in Claude's response.

What's Happening Under the Hood

When you ask a question in Claude for Desktop:

1. The client (Claude for Desktop) sends your question to the Claude LLM.

2. Claude analyzes the available tools (including your `generate-presentation` tool) and decides if and how to use it.

3. If Claude decides to use your tool, it sends a request to Claude for Desktop.

4. Claude for Desktop executes the chosen tool by communicating with your MCP server (which it launched based on `claude_desktop_config.json`) over stdio.

5. Your server runs the tool logic (calls the Gamma API).

6. The results (presentation URL or error) are sent back from your server to Claude for Desktop, then to the LLM.

7. Claude formulates a natural language response incorporating the tool's output.

8. The response is displayed to you!

Troubleshooting

• Server Not Detected by Claude for Desktop:
  • Double-check the absolute paths in `claude_desktop_config.json` for `cwd` and potentially `command`.
  • Ensure your server name in the config (`gamma-presentation-generator` in the example) is unique.
  • Verify that `claude_desktop_config.json` is correctly formatted JSON.
  • Make sure your server runs correctly on its own using `npx ts-node src/index.ts` before trying to integrate with Claude. Check for any errors in the server's console output.
  • Ensure there are no firewalls or security software blocking `npx` or `node` from executing or communicating.
• Errors from the Server:
  • Check the console output of your `gamma-mcp-server` (the terminal where you ran `npx ts-node src/index.ts`). It might show errors from the Gamma API or within the server logic.
  • Ensure your `GAMMA_API_KEY` is correct and has not expired.
  • Verify network connectivity.
• Claude Doesn't Use the Tool:
  • Make sure the tool description in `src/index.ts` (`server.tool(...)`) is clear and accurately describes what the tool does and its parameters. This helps the LLM decide when to use it.
  • Ensure the parameter descriptions in the Zod schema are also clear.
• `ts-node` or Module Issues:
  • Ensure `typescript` and `ts-node` are installed locally in your project (`npm ls ts-node typescript`).
  • Check your `tsconfig.json` for compatibility with your Node.js version and module system (ESM vs CommonJS). If using ESM (`"type": "module"` in `package.json`), ensure `ts-node` is compatible or use `ts-node-esm`. The provided `index.ts` uses ES module imports.

This guide should provide a comprehensive overview of setting up and using your Gamma MCP server. Happy presenting!