GranolaMCP

A comprehensive Python library and CLI tool for accessing and analyzing Granola.ai meeting data, featuring a complete MCP (Model Context Protocol) server for AI integration.

📋 Changelog

2025-07-04 - New Collect Command 🎯

• NEW: Added granola collect command for exporting your own words from meetings
• FEATURE: Automatically filters microphone audio (your spoken words) vs system audio (what you heard)
• FEATURE: Organizes exported text by day into YYYY-MM-DD.txt files
• FEATURE: Supports flexible date ranges (--last 7d, --from/--to)
• FEATURE: Optional timestamps and meeting metadata inclusion
• FEATURE: Minimum word filtering to exclude short utterances
• USE CASE: Perfect for creating LLM training datasets from your own speech

Overview

GranolaMCP provides complete access to Granola.ai meeting data through multiple interfaces:

• 📚 Python Library - Programmatic access to meetings, transcripts, and summaries
• 💻 Command Line Interface - Rich CLI with advanced filtering and analytics
• 🤖 MCP Server - Model Context Protocol server for AI integration (Claude, etc.)
• 📊 Analytics & Visualization - Comprehensive statistics with ASCII charts

Data Source

GranolaMCP operates entirely on local cache files - it reads meeting data directly from Granola's local cache file (cache-v3.json) without making any API calls to Granola's servers. This approach provides:

• 🔌 No Network Dependency - Works completely offline
• ⚡ Fast Access - Direct file system access with no API rate limits
• 🔒 Privacy Focused - Your meeting data never leaves your machine
• 🛡️ No Authentication - No need to manage API keys or tokens

Alternative Approach Available: While not implemented in this library, it's technically possible to extract access tokens from Granola's supabase.json configuration file and communicate directly with the Granola API. However, the cache-based approach provides better performance, privacy, and reliability for most use cases.

✨ Key Features

Core Data Access

• 🔍 Smart JSON Parsing - Handles Granola's complex double-JSON cache structure
• 📝 AI Summary Extraction - Separates AI-generated summaries from human notes
• 💬 Full Transcript Access - Complete speaker-identified transcripts with timing
• 📁 Folder Organization - Meeting organization by folders (OPSWAT, Mozilla, Personal, etc.)
• 🕐 Accurate Duration Calculation - Real meeting duration from transcript timing
• 🏷️ Rich Metadata - Participants, timestamps, and meeting context

Advanced CLI Interface

• 🎯 Intelligent Filtering - Filter by date, participant, title, or folder
• 📊 Table Display - Clean tables showing transcript/summary word counts
• 🔍 Smart Search - Search across titles, content, and participants
• 📈 Analytics Dashboard - Meeting frequency, duration patterns, and trends
• 🎨 Beautiful Output - Color-coded, formatted terminal displays
• 📄 Export Capabilities - Export to markdown with full formatting

MCP Server for AI Integration

• 🤖 8 Comprehensive Tools - Complete meeting data access for AI assistants
• 🔌 Claude Desktop Integration - Ready-to-use configuration for Claude
• 📡 JSON-RPC Protocol - Standard MCP protocol implementation
• ⚡ Real-time Access - Live access to your latest meeting data
• 🛡️ Robust Error Handling - Graceful handling of missing data and errors

Enterprise-Ready Features

• 🐍 Zero Dependencies - Pure Python standard library only
• ⚙️ Flexible Configuration - Environment variables, .env files, CLI arguments
• 🕐 Timezone Aware - Proper UTC to local timezone conversion
• 📅 Flexible Date Parsing - Relative (3d, 24h, 1w) and absolute dates
• 🎯 Production Ready - Comprehensive error handling and logging

Installation

# Install from source
git clone https://github.com/pedramamini/GranolaMCP.git
cd GranolaMCP
pip install -e .

# Or install from PyPI (when available)
pip install granola-mcp

Quick Start

1. Configuration

Copy the example configuration file and update the cache path:

cp .env.example .env

Edit .env to set your Granola cache file path:

GRANOLA_CACHE_PATH=/Users/pedram/Library/Application Support/Granola/cache-v3.json

2. Basic Usage

from granola_mcp import GranolaParser
from granola_mcp.utils.date_parser import parse_date
from granola_mcp.core.timezone_utils import convert_utc_to_cst

# Initialize parser
parser = GranolaParser()

# Load and parse cache
cache_data = parser.load_cache()
meetings = parser.get_meetings()

print(f"Found {len(meetings)} meetings")

# Work with individual meetings
from granola_mcp.core.meeting import Meeting

for meeting_data in meetings[:5]:  # First 5 meetings
    meeting = Meeting(meeting_data)
    print(f"Meeting: {meeting.title}")
    print(f"Start: {meeting.start_time}")
    print(f"Participants: {', '.join(meeting.participants)}")

    if meeting.has_transcript():
        transcript = meeting.transcript
        print(f"Transcript: {transcript.word_count} words")
    print("---")

3. Date Parsing Examples

from granola_mcp.utils.date_parser import parse_date, get_date_range

# Parse relative dates
three_days_ago = parse_date("3d")      # 3 days ago
last_week = parse_date("1w")           # 1 week ago
yesterday = parse_date("24h")          # 24 hours ago

# Parse absolute dates
specific_date = parse_date("2025-01-01")
specific_datetime = parse_date("2025-01-01 14:30:00")

# Get date ranges
start_date, end_date = get_date_range("1w", "1d")  # From 1 week ago to 1 day ago

4. Timezone Conversion

from granola_mcp.core.timezone_utils import convert_utc_to_cst
import datetime

# Convert UTC timestamp to CST
utc_time = datetime.datetime.now(datetime.timezone.utc)
cst_time = convert_utc_to_cst(utc_time)

print(f"UTC: {utc_time}")
print(f"CST: {cst_time}")

💻 CLI Usage

The CLI provides powerful commands for exploring and analyzing meeting data with advanced features:

List Meetings with Rich Display

# List recent meetings with word counts and folders
python -m granola_mcp list --last 7d

# Filter by folder (OPSWAT, Mozilla, Personal, etc.)
python -m granola_mcp list --folder Mozilla --limit 10

# Search meetings by title
python -m granola_mcp list --title-contains "standup" --folder OPSWAT

# Filter by participant and date range
python -m granola_mcp list --participant "john@example.com" --from 30d

# Sort by different criteria
python -m granola_mcp list --sort-by duration --reverse --limit 10

Table Output Features:

• Meeting ID (shortened for readability)
• Title with smart truncation
• Date and time in local timezone
• Accurate duration from transcript timing
• Transcript word count (6.0k format for large numbers)
• AI Summary word count (from extracted summaries)
• Folder organization (Mozilla, OPSWAT, Personal, etc.)

Show Meeting Details

# Show meeting overview with availability indicators
python -m granola_mcp show <meeting-id>

# Show AI-generated summary (structured content)
python -m granola_mcp show <meeting-id> --summary

# Show human notes/transcript content
python -m granola_mcp show <meeting-id> --notes

# Show full transcript with speakers
python -m granola_mcp show <meeting-id> --transcript

# Show everything including metadata
python -m granola_mcp show <meeting-id> --all

Meeting Display Features:

• Clear availability indicators (AI Summary: Available/Not available)
• Separated AI summaries vs human notes
• Full speaker-identified transcripts
• Rich metadata with proper timezone conversion
• Participant lists and tags

Export Meetings

# Export meeting to markdown with full formatting
python -m granola_mcp export <meeting-id>

# Export without transcript for summaries only
python -m granola_mcp export <meeting-id> --no-transcript

# Save to file with proper formatting
python -m granola_mcp export <meeting-id> > meeting.md

Statistics & Analytics Dashboard

# Comprehensive overview with meeting statistics
python -m granola_mcp stats --summary

# Meeting frequency analysis with ASCII charts
python -m granola_mcp stats --meetings-per-day --last 30d
python -m granola_mcp stats --meetings-per-week --last 12w
python -m granola_mcp stats --meetings-per-month --last 6m

# Duration analysis (only for meetings with transcripts)
python -m granola_mcp stats --duration-distribution

# Participant collaboration patterns
python -m granola_mcp stats --participant-frequency

# Time pattern analysis (peak hours, busiest days)
python -m granola_mcp stats --time-patterns

# Content analysis with word counts
python -m granola_mcp stats --word-analysis

# Complete analytics dashboard
python -m granola_mcp stats --all

Collect Your Own Words for LLM Training

# Collect your own words from last 7 days
granola collect --last 7d --output-dir ./my-words

# Collect from specific date range
granola collect --from 2025-01-01 --to 2025-01-31 --output-dir ./january-words

# Include timestamps and meeting metadata
granola collect --last 30d --output-dir ./my-words --include-timestamps --include-meeting-info

# Filter out very short utterances (minimum 3 words)
granola collect --last 30d --output-dir ./my-words --min-words 3

# Collect all available data
granola collect --last 2y --output-dir ./complete-dataset --min-words 1

Key Features:

• Speaker Separation: Automatically filters your words (microphone source) from what you heard (system source)
• Daily Organization: Creates separate YYYY-MM-DD.txt files for each day
• LLM Ready: Perfect format for creating training datasets from your own speech
• Flexible Filtering: Date ranges, minimum word counts, optional metadata
• File Management: Safely overwrites existing files with identical content