Gong Transcripts MCP Server

Model Context Protocol (MCP) server providing AI agents with intelligent access to Gong call transcripts through full-text search.

Features

• Search Performance - Adaptive query optimization reducing response times by up to 77% for complex queries
• Full-Text Search - SQLite FTS5 with BM25 ranking, phrase matching, and automatic query expansion
• Filtering - Speaker affiliation, workspace, date range, and relevance-based filtering
• Caching - 60-second result cache with LRU eviction for instant repeated queries
• Batch Processing - Multi-query searches in single MCP call for maximum efficiency
• Dual Workspace Support - Separate Sales and Customer Success databases with unified search
• Multiple Export Formats - CSV, Markdown (Obsidian-compatible), and structured JSON
• Reliability - Request serialization, error handling, and automatic sync management
• Secure Operations - Input validation, secure database access, and controlled Python subprocess execution

Installation

Prerequisites

• Node.js 18+ and npm
• Python 3.8+ with Gong retrieval system
  • The server automatically detects Python in common locations
  • If Python detection fails, see Troubleshooting Guide
• Gong API credentials (GONG_ACCESS_KEY, GONG_SECRET)
• SQLite databases - Pre-built from Gong transcripts (see Cache Build Guide)

Note: Workspace IDs (GONG_WORKSPACE_SALES_ID, GONG_WORKSPACE_CS_ID) are optional - only needed for syncing new data from Gong API. Search filtering uses workspace metadata from calls, not environment variables.

Python Installation

The gong-mcp server requires Python 3.8+ to process Gong transcripts. The server automatically searches for Python in:

1. GONG_PYTHON_PATH environment variable (if set)
2. Project virtual environment (venv/bin/python3)
3. Common system locations (/usr/local/bin/python3, /opt/homebrew/bin/python3, etc.)
4. System PATH (which python3)

For development, we recommend using a virtual environment:

cd /path/to/gong_transcripts
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

If you encounter Python detection issues, see the Troubleshooting Guide.

Quick Start

# Install dependencies
npm install

# Build TypeScript
npm run build

# Production installation (sync to production directory)
./scripts/install-prod.sh

Environment Setup

Create .env in the parent gong_transcripts directory:

GONG_ACCESS_KEY=your_access_key
GONG_SECRET=your_secret_key

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gong-transcripts": {
      "command": "node",
      "args": ["/path/to/gong-transcripts-prod/lib/mcp-server/dist/index.js"],
      "env": {
        "GONG_ACCESS_KEY": "your_access_key",
        "GONG_SECRET": "your_secret_key",
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      }
    }
  }
}

Note: The PATH environment variable helps the MCP server locate Python. If you encounter spawn python3 ENOENT errors, ensure this is set or use GONG_PYTHON_PATH to specify the exact Python location. See Troubleshooting for more details.

Available Tools

Core Search Tools

search_conversations

Search for specific phrases across all conversation transcripts.

Parameters:

• query (required): Search phrase(s) - space-separated terms automatically expand to OR search
• team (optional): Filter by workspace - "sales" (prospects), "customer_success" (existing customers), or "both" (default: "both")
• timeframe (optional): Date range - "YYYY-MM-DD to YYYY-MM-DD", "last 30 days", "last 6 months", etc.
• options (optional): Advanced options for context, grouping, etc.

Workspace Filtering:

• Workspaces are determined from call metadata (not environment variables)
• Sales = prospect/opportunity calls (4,815+ calls)
• Customer Success = existing customer calls (964+ calls)
• Filtering works automatically without needing GONG_WORKSPACE_*_ID configuration

Performance: Automatically optimized based on query complexity (see Performance Optimizations)

Example:

{
  "query": "carousel pricing demo",
  "team": "sales",
  "timeframe": "2025-07-01 to 2025-08-31"
}

search_conversations_batch

⭐ Preferred for multiple terms - Execute multiple searches in a single call.

Parameters:

• queries (required): Array of search queries (max 10)
• team, timeframe, options: Same as search_conversations

Returns: Results grouped by query with individual statistics.

search_customer_conversations

Search specifically for customer/prospect mentions (external speakers only).

Parameters: Same as search_conversations, automatically filters to external speakers.

Export Tools

export_to_obsidian

Export search results to Obsidian-compatible Markdown with rich frontmatter.

Parameters:

• query (required): Search query
• team, timeframe (optional): Same as search tools
• output_path (required): Export file path

Output Format:

---
title: "Search Results: carousel"
date: 2025-01-15
tags: [gong, search-results, sales]
workspace: sales
total_results: 25
---

## 2025-07-15: Demo Call with Acme Corp
**Speaker:** John Smith (Customer)
> We love the carousel feature...

export_to_csv

Export search results to CSV format.

Parameters:

• query, team, timeframe: Same as search tools
• output_path (required): Export file path

Utility Tools

sync_gong_data

Trigger manual sync with Gong API to update databases.

Parameters:

• workspaces (optional): Array of workspaces to sync - ["sales", "customer_success"]
• force (optional): Force full sync even if recent sync exists

Database Management Tools

delete_calls

Delete calls from the database based on date range, workspace, or specific call IDs. Automatically maintains FTS5 search index integrity through database triggers.

Parameters:

• beforeDate (optional): Delete calls before this date (YYYY-MM-DD format)
• afterDate (optional): Delete calls after this date (YYYY-MM-DD format)
• dateRange (optional): Delete calls within date range {from: "YYYY-MM-DD", to: "YYYY-MM-DD"}
• workspace (optional): Filter by workspace - "sales", "customer_success", or "both"
• callIds (optional): Array of specific call IDs to delete
• autoVacuum (optional): Automatically run VACUUM after deletion to reclaim space (default: true)

Note: At least one deletion criteria must be specified. All date inputs are validated for YYYY-MM-DD format.

Examples:

// Delete all calls before a specific date
{
  "beforeDate": "2025-01-01",
  "autoVacuum": true
}

// Delete calls in a date range for specific workspace
{
  "dateRange": {
    "from": "2024-12-01",
    "to": "2024-12-31"
  },
  "workspace": "sales"
}

// Delete specific calls by ID
{
  "callIds": ["call-123", "call-456"],
  "autoVacuum": false
}

vacuum_database

Optimize database and reclaim disk space after deletions. Runs SQLite VACUUM command to compact the database file.

Parameters: None

Use when:

• After large deletions with autoVacuum: false
• Periodic maintenance to optimize database performance
• Database file size needs reduction

get_database_management_stats

View database statistics including total records, disk usage, and workspace distribution.

Parameters: None

Returns:

• Total calls and utterances count
• Database file size in MB
• Breakdown by workspace (sales/customer_success)
• Last modification time

Example Workflows

Simple Search

User: "What did customers say about our carousel feature in July?"
Agent: Uses search_conversations
  → query: "carousel"
  → team: "both"
  → timeframe: "2025-07-01 to 2025-07-31"
  → Returns 25 relevant matches with context

Multi-Term Analysis

User: "Find all mentions of pricing, competitors, and objections"
Agent: Uses search_conversations_batch (efficient!)
  → queries: ["pricing", "competitors", "objections"]
  → Returns grouped results for each term

Customer-Specific Research

User: "What problems did customers report last quarter?"
Agent: Uses search_customer_conversations
  → query: "problem issue challenge bug error"
  → timeframe: "last 90 days"
  → Auto-filters to external speakers only

Export for Analysis

User: "Export carousel mentions to Obsidian"
Agent: Uses export_to_obsidian
  → query: "carousel"
  → output_path: "/path/to/vault/Carousel Analysis.md"
  → Creates markdown with frontmatter and organized results

Architecture

AI Agent (Claude/Raycast)
    ↓ MCP Protocol (stdio)
MCP Server (TypeScript/Node.js)
    ↓ Direct database access
SQLite FTS5 Databases (sales.db, customer_success.db)
    ↑ Periodic sync
Python Gong Retrieval System
    ↓ API calls
Gong API (call transcripts)

Key Components

• MCP Server (src/server/GongCallsServer.ts) - Protocol handler, tool registration, request routing
• Search Engine (src/search/PhraseSearchEngine.ts) - FTS5 queries, BM25 ranking, multi-phrase OR logic
• Database Engine (src/search/DatabaseSearchEngine.ts) - SQLite connection pooling, serialization, caching
• Search Tools (src/tools/*Tool.ts) - Tool implementations with adaptive optimization
• Workspace Manager (src/workspace/WorkspaceManager.ts) - Multi-database coordination
• Sync Manager (src/sync/SyncManager.ts) - Background data updates via Python subprocess

Performance Optimizations

This server includes 6 adaptive performance optimizations that automatically adjust based on query complexity:

1. Adaptive Database Limiting - Fetch 50-85% fewer results for complex queries
2. Adaptive Result Limiting - Return 0-60% fewer results for multi-phrase searches
3. Adaptive Context Scaling - Reduce context words by up to 60% for complex queries
4. Relevance Filtering - Remove low-quality matches using BM25 threshold
5. Result Deduplication - Eliminate duplicate call/position pairs
6. Response Size Limiting - Hard 50KB cap prevents transport buffer overflow

Performance Impact:

• Single-phrase queries: 50% less I/O, 40% smaller responses
• Complex queries (6+ phrases): 85% less I/O, 77% smaller responses

See Performance Optimizations for full details.

Development

Project Structure

mcp-server/
├── src/
│   ├── server/          # MCP server implementation
│   ├── search/          # Search engines and database access
│   ├── tools/           # MCP tool implementations
│   ├── workspace/       # Multi-workspace coordination
│   ├── sync/            # Data sync management
│   └── index.ts         # Entry point
├── dist/                # Compiled JavaScript (generated)
├── tests/               # Test suite
├── scripts/             # Utility scripts
├── docs/
│   ├── implementation/  # Production documentation
│   └── wip/            # Work in progress
├── package.json
├── tsconfig.json
└── README.md

Development Commands

npm run dev          # Development with auto-reload
npm run build        # Compile TypeScript
npm test             # Run test suite
npm run lint         # ESLint checks

Adding New Tools

1. Create tool class in src/tools/ extending base tool
2. Implement tool logic with proper error handling
3. Register in GongCallsServer.ts tool list and handler
4. Add factory method in DependencyContainer.ts
5. Update this README

Troubleshooting

MCP Connection Issues

Symptom: Tools not appearing in Claude/Raycast

• Verify MCP configuration syntax (see Configuration section)
• Check server path is correct
• Restart Claude/Raycast completely

Symptom: -32800 timeout errors (Raycast)

• Known Raycast MCP client issue with ~10 second timeout
• Server includes automatic optimizations (see Raycast Optimizations)
• Workaround: Use Claude Desktop for complex queries

Search Issues

Symptom: No results for valid queries

• Check date range includes data (database covers specific date ranges)
• Verify workspace filter ("sales" vs "customer_success" vs "both")
• Use sync_gong_data tool to update databases

Symptom: Customer searches return 0 results

• Ensure using search_customer_conversations (auto-filters to external speakers)
• Check database has external speaker data (requires proper Gong sync)

Debug Logging

Server logs to /tmp/gong-mcp-debug.log:

# View recent logs
tail -f /tmp/gong-mcp-debug.log

# Check specific search
grep "SearchTool.searchConversations: COMPLETE" /tmp/gong-mcp-debug.log

# Clear logs
rm /tmp/gong-mcp-debug.log

Performance Issues

Symptom: Slow searches

• Check database size and indexing (see Database Search)
• Review logs for cache hit rate
• Consider narrowing date ranges or using more specific queries

Symptom: Large response sizes

• Server auto-limits to 50KB (see logs for truncation warnings)
• Use more specific queries to reduce result count
• Leverage adaptive optimizations (automatic for complex queries)

Documentation

• Cache Build Guide - Building SQLite databases from Gong data
• Database Search - FTS5 implementation details
• Performance Optimizations - Adaptive optimization system
• Raycast Optimizations - MCP client timeout handling

License

MIT