GranolaMCP

★ 42

from pedramamini

An MCP server for accessing and analyzing Granola.ai meeting data.

🔥🔥🔥✓ VerifiedFreeNeeds API keys

#email #automation #analytics #database #git

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

🤖 MCP Server for AI Integration

Start the MCP server to integrate with AI assistants like Claude Desktop:

# Start MCP server
python -m granola_mcp.mcp

# Start with debug logging
python -m granola_mcp.mcp --debug

# Start with custom cache path
python -m granola_mcp.mcp --cache-path "/path/to/cache.json"

Claude Desktop Integration

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

{
  "mcpServers": {
    "granola-mcp": {
      "command": "python",
      "args": ["-m", "granola_mcp.mcp"],
      "env": {
        "GRANOLA_CACHE_PATH": "/Users/[username]/Library/Application Support/Granola/cache-v3.json"
      }
    }
  }
}

Available MCP Tools

The server provides 10 comprehensive tools:

get_recent_meetings - Get the most recent X meetings (goes back as far as needed)
list_meetings - Simple meeting list with date filters (defaults to last 3 days)
search_meetings - Advanced search with text, participant, and date filters
get_meeting - Complete meeting details with metadata
get_transcript - Full transcript with speaker identification
get_meeting_notes - Structured AI summaries and human notes
list_participants - Participant analysis with meeting history
get_statistics - Generate analytics (summary, frequency, duration, patterns)
export_meeting - Export meetings in markdown format
analyze_patterns - Analyze meeting patterns and trends

MCP Usage Examples

// Get the 5 most recent meetings (regardless of date)
{
  "name": "get_recent_meetings",
  "arguments": {
    "count": 5
  }
}

// List recent meetings (last 3 days by default)  
{
  "name": "list_meetings",
  "arguments": {
    "limit": 10
  }
}

// List meetings from last week
{
  "name": "list_meetings", 
  "arguments": {
    "from_date": "7d",
    "limit": 5
  }
}

// Search meetings with text query
{
  "name": "search_meetings",
  "arguments": {
    "query": "project review",
    "from_date": "7d"
  }
}

// Get complete meeting details
{
  "name": "get_meeting",
  "arguments": {
    "meeting_id": "f47f8acd-70bd-49b7-8b0d-83c49eee07d1"
  }
}

// Get meeting statistics
{
  "name": "get_statistics",
  "arguments": {
    "stat_type": "summary"
  }
}

Project Structure

granola_mcp/
├── __init__.py              # Main package exports
├── core/                    # Core functionality
│   ├── __init__.py
│   ├── parser.py           # JSON cache parser
│   ├── meeting.py          # Meeting data model
│   ├── transcript.py       # Transcript data model
│   └── timezone_utils.py   # UTC to CST conversion
├── utils/                   # Utility functions
│   ├── __init__.py
│   ├── config.py           # Configuration management
│   └── date_parser.py      # Date parsing utilities
├── cli/                     # CLI tools (Phase 2 & 4)
│   ├── __init__.py
│   ├── main.py             # Main CLI entry point
│   ├── commands/           # CLI commands
│   │   ├── list.py         # List meetings
│   │   ├── show.py         # Show meeting details
│   │   ├── export.py       # Export meetings
│   │   └── stats.py        # Statistics & analytics
│   └── formatters/         # Output formatters
│       ├── colors.py       # ANSI color utilities
│       ├── table.py        # Table formatting
│       ├── markdown.py     # Markdown export
│       └── charts.py       # ASCII charts & visualizations
└── mcp/                     # MCP server (Phase 3)
    └── __init__.py

Architecture

See ARCHITECTURE.md for detailed architecture documentation.

Roadmap

See ROADMAP.md for development roadmap and future plans.

Copy & paste — that's it

# 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

Before it works, you'll need: GRANOLA_CACHE_PATH

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

Requirements

Python 3.12 or higher
No external dependencies (uses only Python standard library)

GranolaMCP

📋 Changelog

2025-07-04 - New Collect Command 🎯

Overview

Data Source

✨ Key Features

Core Data Access

Advanced CLI Interface

MCP Server for AI Integration

Enterprise-Ready Features

🤖 MCP Server for AI Integration

Claude Desktop Integration

Available MCP Tools

MCP Usage Examples

Project Structure

Architecture

Roadmap

Installation

Quick Start

1. Configuration

2. Basic Usage

3. Date Parsing Examples

4. Timezone Conversion

💻 CLI Usage

List Meetings with Rich Display

Show Meeting Details

Export Meetings

Statistics & Analytics Dashboard

Collect Your Own Words for LLM Training

Requirements

License