gongio-mcp

# Gong MCP Server

[![npm version](https://img.shields.io/npm/v/gongio-mcp)](https://www.npmjs.com/package/gongio-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<img src="gong.png" alt="A cute red panda hitting a gong" width="300" />

An MCP (Model Context Protocol) server that provides access to your Gong.io data. Query calls, transcripts, users, keyword trackers, and more directly from Claude or any MCP-compatible client.

## Tools Quick Reference

| Tool | Description |
|------|-------------|
| [`list_calls`](#list_calls) | List calls with date/workspace filtering |
| [`get_call`](#get_call) | Get metadata for a specific call |
| [`get_call_summary`](#get_call_summary) | AI summary: key points, topics, action items |
| [`get_call_transcript`](#get_call_transcript) | Full speaker-attributed transcript (paginated) |
| [`search_calls`](#search_calls) | Rich call search — participant, customer, tracker, scope, duration, title, and more |
| [`search_calls_by_account`](#search_calls_by_account) | Find calls involving a specific account/company by email domain |
| [`search_calls_by_opportunity`](#search_calls_by_opportunity) | Find calls linked to specific CRM Opportunities |
| [`search_transcripts`](#search_transcripts) | Free-text keyword search across transcript sentences |
| [`get_trackers`](#get_trackers) | List keyword trackers (competitors, topics, etc.) |
| [`list_workspaces`](#list_workspaces) | List workspaces and get IDs for use in other tools |
| [`list_library_folders`](#list_library_folders) | List public call library folders |
| [`get_library_folder_calls`](#get_library_folder_calls) | Get calls saved in a specific library folder |
| [`get_user`](#get_user) | Get a specific user's profile |
| [`search_users`](#search_users) | Search/filter users by IDs or creation date |
| [`list_users`](#list_users) | List all workspace users |


## Response Size & Context Limits

`search_calls` can return a lot of data. Under the hood it:

- Auto-paginates up to **~5000 calls** (50 API pages) per query
- Applies client-side filters (participant, customer, tracker, duration, etc.) after pagination
- Returns a rich per-call format (metadata + summary + topics + participants) by default

**Guardrails built in:**

- If the formatted output would exceed **`MAX_MCP_OUTPUT_LENGTH`** (default `50000` chars, configurable via env var), the tool **automatically falls back to a compact table** with a warning. You still get every call ID and title — drill in with `get_call_summary` on specific ones.
- `include: ["outline"]` is **expensive** (~80KB per call). Avoid it in multi-call searches.
- Tracker data is filtered to only show trackers matching your `trackers` filter (or non-zero trackers if no filter) — no more walls of `(0x)` noise.

**If your query hits the output cap, narrow it:**

1. Tighten `fromDateTime` / `toDateTime`
2. Add `scope: "External"` or `scope: "Internal"`
3. Add `minDuration: 600` to skip short no-shows
4. Add `customerName` or `trackers` filter
5. Drop heavy `include` options like `outline`

## Prerequisites

- Node.js 18+ **or** Docker
- Gong API credentials (Access Key and Secret)

<details>
<summary><strong>Getting API Credentials</strong></summary>

1. Log into Gong as an admin
2. Go to **Company Settings** → **Ecosystem** → **API**
3. Click **Create API Key**
4. Save both the Access Key and Secret (the secret is only shown once)

</details>

<details>
<summary><strong>Installation</strong></summary>

### Option 1: npx (no install required)

```bash
npx gongio-mcp
```

### Option 2: Global npm install

```bash
npm install -g gongio-mcp
gongio-mcp
```

### Option 3: From source

```bash
git clone https://github.com/JustinBeckwith/gongio-mcp.git
cd gongio-mcp
npm install
npm run build
node dist/index.js
```

### Option 4: Docker (build locally)

```bash
git clone https://github.com/JustinBeckwith/gongio-mcp.git
cd gongio-mcp
docker build -t gongio-mcp .
docker run --rm -i \
  -e GONG_ACCESS_KEY=your-access-key \
  -e GONG_ACCESS_KEY_SECRET=your-secret-key \
  gongio-mcp
```

</details>

<details>
<summary><strong>Configuration</strong></summary>

Set your Gong credentials as environment variables:

```bash
export GONG_ACCESS_KEY="your-access-key"
export GONG_ACCESS_KEY_SECRET="your-secret-key"
```

Or pass them inline:

```bash
GONG_ACCESS_KEY=your-key GONG_ACCESS_KEY_SECRET=your-secret npx gongio-mcp
```

</details>

<details>
<summary><strong>Client Setup</strong></summary>

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

**Using npx:**
```json
{
  "mcpServers": {
    "gong": {
      "command": "npx",
      "args": ["gongio-mcp"],
      "env": {
        "GONG_ACCESS_KEY": "your-access-key",
        "GONG_ACCESS_KEY_SECRET": "your-secret-key"
      }
    }
  }
}
```

**Using Docker:**
```json
{
  "mcpServers": {
    "gong": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "GONG_ACCESS_KEY",
               "-e", "GONG_ACCESS_KEY_SECRET",
               "gongio-mcp"],
      "env": {
        "GONG_ACCESS_KEY": "your-access-key",
        "GONG_ACCESS_KEY_SECRET": "your-secret-key"
      }
    }
  }
}
```

### Claude Code

**Using npx:**
```bash
claude mcp add gong -e GONG_ACCESS_KEY=your-key -e GONG_ACCESS_KEY_SECRET=your-secret -- npx gongio-mcp
```

**Using Docker (after `docker build -t gongio-mcp .`):**
```bash
claude mcp add gong -e GONG_ACCESS_KEY=your-key -e GONG_ACCESS_KEY_SECRET=your-secret -- docker run --rm -i -e GONG_ACCESS_KEY -e GONG_ACCESS_KEY_SECRET gongio-mcp
```

</details>

## Available Tools

<a name="list_calls"></a>
<details>
<summary><code>list_calls</code> — List Gong calls with date filtering</summary>

List calls with optional date range and workspace filters. Returns minimal call metadata (ID, title, date, duration).

**Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `fromDateTime` | No | Start date in ISO 8601 format (e.g., `2024-01-01T00:00:00Z`) |
| `toDateTime` | No | End date in ISO 8601 format (e.g., `2024-01-31T23:59:59Z`) |
| `workspaceId` | No | Filter calls by workspace ID (use `list_workspaces` to find IDs) |
| `cursor` | No | Pagination cursor for next page |

</details>

<a name="get_call"></a>
<details>
<summary><code>get_call</code> — Get metadata for a specific call</summary>

Get the URL, timing, direction, scope, system, and other metadata for one call. Faster than `get_call_summary` when you only need call metadata.

**Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `callId` | Yes | Gong call ID (numeric string) |

</details>

<a name="get_call_summary"></a>
<details>
<summary><code>get_call_summary</code> — AI-generated call summary</summary>

Get an AI-generated summary including brief overview, key points, topics, action items, and detailed outline. This is the recommended way to understand a call — use `get_call_transcript` only if you need exact quotes.

**Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `callId` | Yes | Gong call ID (numeric string) |

</details>

<a name="get_call_transcript"></a>
<details>
<summary><code>get_call_transcript</code> — Full speaker-attributed transcript</summary>

Get the raw transcript with speaker attribution. Transcripts are paginated (default 10KB) to prevent context overflow — use `maxLength` and `offset` to navigate.

**Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `callId` | Yes | Gong call ID (numeric string) |
| `maxLength` | No | Maximum characters to return (default: 10000, max: 100000) |
| `offset` | No | Character offset to start from for pagination (default: 0) |

</details>

<a name="search_calls"></a>
<details>
<summary><code>search_calls</code> — Advanced call search</summary>

Search calls with advanced filters including participant lookup, customer name search, and rich content selection. Automatically paginates through all results and returns participant info, brief summary, and topics by default.

**Parameters:**

*Date & workspace*

| Parameter | Description |
|-----------|-------------|
| `fromDateTime` | Start date in ISO 8601 format |
| `toDateTime` | End date in ISO 8601 format |
| `workspaceId` | Filter by workspace ID (use `list_workspaces` to find IDs) |
| `callIds` | Array of specific call IDs to retrieve |

*Host / participant*

| Parameter | Description |
|-----------|-------------|
| `primaryUserIds` | Host user IDs (server-side) |
| `primaryUserEmails` | Host emails (case-insensitive) |
| `excludePrimaryUserIds` | Exclude these host user IDs |
| `participantUserIds` | Any participant (host/attendee/invitee) user IDs |
| `excludeParticipantUserIds` | Exclude calls where any participant has these user IDs |
| `participantEmails` | Any participant emails (case-insensitive) |
| `excludeParticipantEmails` | Exclude calls where any participant has these emails |

*Content & customer*

| Parameter | Description |
|-----------|-------------|
| `customerName` | Fuzzy match against CRM account name, external email domains, and titles |
| `titleContains` | Substring match on call title (case-insensitive) |
| `trackers` | Calls where matching tracker(s) fired (count > 0). Workspace-specific — use `get_trackers` to discover |

*Metadata*

| Parameter | Description |
|-----------|-------------|
| `scope` | `External`, `Internal`, or `Unknown` |
| `direction` | `Inbound`, `Outbound`, `Conference`, or `Unknown` |
| `system` | Conferencing platform (e.g., `Zoom`) — case-insensitive substring |
| `language` | Language code (e.g., `eng`) — case-insensitive exact match |
| `minDuration` | Minimum duration in seconds |
| `maxDuration` | Maximum duration in seconds |

*Response shape*

| Parameter | Descripti