README.md•5.33 kB
# Gamma MCP Server
A Model Context Protocol (MCP) server for Gamma AI that provides tools and resources for generating presentations, documents, and webpages using the Gamma Public API.
## Features
### Resources (2)
- **`gamma://folders`** - List all folders (channels) in your Gamma workspace
- **`gamma://themes`** - List all available themes for generation
### Tools (1)
- **`generate_gamma`** - Generate Gamma content with AI, including automatic polling until completion
## Prerequisites
- Node.js 18+
- Yarn package manager
- A Gamma API key ([get one here](https://gamma.app/settings/api-keys))
## Installation
1. **Install dependencies:**
```bash
yarn install
```
2. **Configure your API key:**
Edit `src/gamma-api.service.ts` and replace the placeholder API key:
```typescript
const GAMMA_API_KEY = 'sk-gamma-your-api-key-here';
```
Replace `'sk-gamma-your-api-key-here'` with your actual Gamma API key.
3. **Build the project:**
```bash
yarn build
```
## Running the Server
### Development mode (with auto-reload):
```bash
yarn dev
```
### Production mode:
```bash
yarn start
```
The server will start on `http://localhost:3000` using streamable HTTP transport.
## Connecting to Claude Desktop
To use this MCP server with Claude Desktop, add it to your Claude configuration:
### macOS/Linux:
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"gamma": {
"command": "node",
"args": ["/absolute/path/to/gamma-mcp-server/dist/index.js"]
}
}
}
```
### Windows:
Edit `%APPDATA%\Claude\claude_desktop_config.json` with similar configuration.
**Important:** Replace `/absolute/path/to/gamma-mcp-server` with the actual absolute path to this project directory.
## Usage Examples
Once connected to Claude Desktop, you can use natural language to interact with Gamma:
### List Available Themes
```
Show me all available Gamma themes
```
### List Workspace Folders
```
What folders do I have in my Gamma workspace?
```
### Generate a Presentation
```
Create a 10-slide presentation about renewable energy using the "Modern Professional" theme
```
### Generate with Export
```
Generate a presentation about AI trends and export it as a PowerPoint file
```
## API Reference
### Resources
#### `gamma://folders`
Returns all workspace folders with pagination automatically handled.
**Response:**
```json
{
"folders": [
{"id": "fold_123", "name": "Marketing"},
{"id": "fold_456", "name": "Sales"}
],
"total": 2
}
```
#### `gamma://themes`
Returns all available themes with pagination automatically handled.
**Response:**
```json
{
"themes": [
{
"id": "theme_123",
"name": "Modern Professional",
"type": "standard",
"colorKeywords": ["blue", "corporate"],
"toneKeywords": ["professional", "clean"]
}
],
"total": 50
}
```
### Tools
#### `generate_gamma`
Generate Gamma content with automatic polling until completion.
**Parameters:**
- `inputText` (required): Content to generate from (max 400k chars)
- `textMode` (required): `"generate"`, `"condense"`, or `"preserve"`
- `format` (optional): `"presentation"`, `"document"`, `"social"`, or `"webpage"` (default: "presentation")
- `numCards` (optional): Number of cards/pages to generate
- `themeId` (optional): Theme ID from the themes resource
- `folderIds` (optional): Array of folder IDs to save the gamma in
- `exportAs` (optional): `"pptx"` or `"pdf"` to generate an export URL
**Returns:**
```json
{
"success": true,
"generationId": "gen_abc123",
"gammaUrl": "https://gamma.app/docs/...",
"exportUrl": "https://gamma.app/export/...",
"credits": {
"deducted": 10,
"remaining": 90
}
}
```
## Development
### Project Structure
```
gamma-mcp-server/
├── src/
│ ├── index.ts # Entry point
│ ├── app.module.ts # NestJS app module
│ ├── gamma-api.service.ts # Gamma API client
│ ├── folders.resource.ts # Folders MCP resource
│ ├── themes.resource.ts # Themes MCP resource
│ └── generate.tool.ts # Generate MCP tool
├── dist/ # Compiled output
├── package.json
├── tsconfig.json
└── README.md
```
### Scripts
- `yarn build` - Compile TypeScript to JavaScript
- `yarn start` - Run the compiled server
- `yarn dev` - Run in development mode with ts-node
- `yarn watch` - Watch mode for TypeScript compilation
## Troubleshooting
### "Invalid API key" error
Make sure you've replaced the placeholder API key in `src/gamma-api.service.ts` with your actual Gamma API key.
### Server won't start
1. Make sure you've run `yarn install` and `yarn build`
2. Check that port 3000 is not already in use
3. Check the console for error messages
### Claude Desktop can't connect
1. Verify the absolute path in your Claude config is correct
2. Make sure the server is built (`yarn build`)
3. Restart Claude Desktop after editing the config
4. Check Claude Desktop logs for connection errors
## Learn More
- [Gamma Public API Documentation](https://developers.gamma.app/docs/getting-started)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP-Nest Framework](https://github.com/rekog-labs/MCP-Nest)
## License
MIT