GranolaMCP

Un servidor MCP para acceder y analizar datos de reuniones de Granola.ai.

GitHub
45
Prueba este MCPPatrocinado

Documentación

GranolaMCP

Una biblioteca integral de Python y herramienta CLI para acceder y analizar datos de reuniones de Granola.ai, con un servidor MCP (Model Context Protocol) completo para integración con IA.

📋 Registro de cambios

2025-07-04 - Nuevo comando Collect 🎯

  • NUEVO: Se agregó el comando granola collect para exportar tus propias palabras de las reuniones
  • CARACTERÍSTICA: Filtra automáticamente el audio del micrófono (tus palabras habladas) frente al audio del sistema (lo que escuchaste)
  • CARACTERÍSTICA: Organiza el texto exportado por día en archivos YYYY-MM-DD.txt
  • CARACTERÍSTICA: Admite rangos de fechas flexibles (--last 7d, --from/--to)
  • CARACTERÍSTICA: Inclusión opcional de marcas de tiempo y metadatos de la reunión
  • CARACTERÍSTICA: Filtrado mínimo de palabras para excluir expresiones cortas
  • CASO DE USO: Perfecto para crear conjuntos de datos de entrenamiento de LLM a partir de tu propio discurso

Descripción general

GranolaMCP proporciona acceso completo a los datos de reuniones de Granola.ai a través de múltiples interfaces:

  • 📚 Biblioteca de Python - Acceso programático a reuniones, transcripciones y resúmenes
  • 💻 Interfaz de línea de comandos - CLI enriquecida con filtrado avanzado y análisis
  • 🤖 Servidor MCP - Servidor de Protocolo de Contexto de Modelo para integración con IA (Claude, etc.)
  • 📊 Análisis y visualización - Estadísticas completas con gráficos ASCII

Fuente de datos

GranolaMCP opera completamente en archivos de caché locales - lee los datos de las reuniones directamente del archivo de caché local de Granola (cache-v3.json) sin realizar llamadas API a los servidores de Granola. Este enfoque proporciona:

  • 🔌 Sin dependencia de red - Funciona completamente sin conexión
  • ⚡ Acceso rápido - Acceso directo al sistema de archivos sin límites de velocidad de API
  • 🔒 Enfocado en la privacidad - Tus datos de reuniones nunca salen de tu máquina
  • 🛡️ Sin autenticación - No es necesario gestionar claves API o tokens

Enfoque alternativo disponible: Aunque no está implementado en esta biblioteca, técnicamente es posible extraer tokens de acceso del archivo de configuración supabase.json de Granola y comunicarse directamente con la API de Granola. Sin embargo, el enfoque basado en caché proporciona mejor rendimiento, privacidad y fiabilidad para la mayoría de los casos de uso.

✨ Características clave

Acceso a datos principales

  • 🔍 Análisis JSON inteligente - Maneja la compleja estructura de caché de doble JSON de Granola
  • 📝 Extracción de resúmenes de IA - Separa los resúmenes generados por IA de las notas humanas
  • 💬 Acceso completo a transcripciones - Transcripciones completas con identificación de hablantes y tiempos
  • 📁 Organización por carpetas - Organización de reuniones por carpetas (OPSWAT, Mozilla, Personal, etc.)
  • 🕐 Cálculo preciso de duración - Duración real de la reunión a partir del tiempo de la transcripción
  • 🏷️ Metadatos enriquecidos - Participantes, marcas de tiempo y contexto de la reunión

Interfaz CLI avanzada

  • 🎯 Filtrado inteligente - Filtrar por fecha, participante, título o carpeta
  • 📊 Visualización en tablas - Tablas limpias que muestran recuentos de palabras de transcripciones/resúmenes
  • 🔍 Búsqueda inteligente - Buscar en títulos, contenido y participantes
  • 📈 Panel de análisis - Frecuencia de reuniones, patrones de duración y tendencias
  • 🎨 Salida hermosa - Visualizaciones de terminal con códigos de color y formato
  • 📄 Capacidades de exportación - Exportar a markdown con formato completo

Servidor MCP para integración con IA

  • 🤖 8 herramientas integrales - Acceso completo a datos de reuniones para asistentes de IA
  • 🔌 Integración con Claude Desktop - Configuración lista para usar para Claude
  • 📡 Protocolo JSON-RPC - Implementación estándar del protocolo MCP
  • ⚡ Acceso en tiempo real - Acceso en vivo a tus datos de reuniones más recientes
  • 🛡️ Manejo robusto de errores - Manejo elegante de datos faltantes y errores

Características listas para empresas

  • 🐍 Cero dependencias - Solo biblioteca estándar pura de Python
  • ⚙️ Configuración flexible - Variables de entorno, archivos .env, argumentos CLI
  • 🕐 Consciente de la zona horaria - Conversión adecuada de UTC a zona horaria local
  • 📅 Análisis flexible de fechas - Fechas relativas (3d, 24h, 1w) y absolutas
  • 🎯 Listo para producción - Manejo integral de errores y registro

Instalación

# 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

Inicio rápido

1. Configuración

Copia el archivo de configuración de ejemplo y actualiza la ruta de caché:

cp .env.example .env

Edita .env para establecer la ruta de tu archivo de caché de Granola:

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

2. Uso básico

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. Ejemplos de análisis de fechas

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. Conversión de zona horaria

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}")

💻 Uso de CLI

La CLI proporciona comandos potentes para explorar y analizar datos de reuniones con características avanzadas:

Listar reuniones con visualización enriquecida

# 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

Características de salida en tabla:

  • ID de reunión (abreviado para legibilidad)
  • Título con truncamiento inteligente
  • Fecha y hora en zona horaria local
  • Duración precisa a partir del tiempo de la transcripción
  • Recuento de palabras de la transcripción (formato 6.0k para números grandes)
  • Recuento de palabras del resumen de IA (de resúmenes extraídos)
  • Organización por carpetas (Mozilla, OPSWAT, Personal, etc.)

Mostrar detalles de la reunión

# 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

Características de visualización de la reunión:

  • Indicadores claros de disponibilidad (Resumen de IA: Disponible/No disponible)
  • Resúmenes de IA separados frente a notas humanas
  • Transcripciones completas con identificación de hablantes
  • Metadatos enriquecidos con conversión adecuada de zona horaria
  • Listas de participantes y etiquetas

Exportar reuniones

# 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

Panel de estadísticas y análisis

# 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

Recopila tus propias palabras para entrenamiento de LLM

# 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

Características clave:

  • Separación de hablantes: Filtra automáticamente tus palabras (fuente de micrófono) de lo que escuchaste (fuente del sistema)
  • Organización diaria: Crea archivos YYYY-MM-DD.txt separados para cada día
  • Listo para LLM: Formato perfecto para crear conjuntos de datos de entrenamiento a partir de tu propio discurso
  • Filtrado flexible: Rangos de fechas, recuentos mínimos de palabras, metadatos opcionales
  • Gestión de archivos: Sobrescribe de forma segura archivos existentes con contenido idéntico

🤖 Servidor MCP para integración con IA

Inicia el servidor MCP para integrarlo con asistentes de IA como 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"

Integración con Claude Desktop

Agrega a tu ~/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"
      }
    }
  }
}

Herramientas MCP disponibles

El servidor proporciona 10 herramientas integrales:

  1. get_recent_meetings - Obtén las X reuniones más recientes (retrocede tanto como sea necesario)
  2. list_meetings - Lista simple de reuniones con filtros de fecha (por defecto, últimos 3 días)
  3. search_meetings - Búsqueda avanzada con filtros de texto, participante y fecha
  4. get_meeting - Detalles completos de la reunión con metadatos
  5. get_transcript - Transcripción completa con identificación de hablantes
  6. get_meeting_notes - Resúmenes estructurados de IA y notas humanas
  7. list_participants - Análisis de participantes con historial de reuniones
  8. get_statistics - Genera análisis (resumen, frecuencia, duración, patrones)
  9. export_meeting - Exporta reuniones en formato markdown
  10. analyze_patterns - Analiza patrones y tendencias de reuniones

Ejemplos de uso de MCP

// 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"
  }
}

Estructura del proyecto

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

Requisitos

  • Python 3.12 o superior
  • Sin dependencias externas (usa solo la biblioteca estándar de Python)

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Arquitectura

Consulta ARCHITECTURE.md para documentación detallada de la arquitectura.

Hoja de ruta

Consulta ROADMAP.md para la hoja de ruta de desarrollo y planes futuros.