GranolaMCP

Um servidor MCP para acessar e analisar dados de reuniões do Granola.ai.

GitHub
45
Experimente este MCPPatrocinado

Documentação

GranolaMCP

Uma biblioteca Python abrangente e ferramenta de CLI para acessar e analisar dados de reuniões do Granola.ai, com um servidor MCP (Model Context Protocol) completo para integração com IA.

📋 Changelog

2025-07-04 - Novo Comando Collect 🎯

  • NOVO: Adicionado o comando granola collect para exportar suas próprias palavras das reuniões
  • RECURSO: Filtra automaticamente o áudio do microfone (suas palavras faladas) versus o áudio do sistema (o que você ouviu)
  • RECURSO: Organiza o texto exportado por dia em arquivos YYYY-MM-DD.txt
  • RECURSO: Suporta intervalos de datas flexíveis (--last 7d, --from/--to)
  • RECURSO: Inclusão opcional de timestamps e metadados da reunião
  • RECURSO: Filtro de palavras mínimas para excluir falas curtas
  • CASO DE USO: Perfeito para criar conjuntos de dados de treinamento de LLM a partir da sua própria fala

Visão Geral

O GranolaMCP fornece acesso completo aos dados de reuniões do Granola.ai por meio de múltiplas interfaces:

  • 📚 Biblioteca Python - Acesso programático a reuniões, transcrições e resumos
  • 💻 Interface de Linha de Comando - CLI rica com filtros avançados e análises
  • 🤖 Servidor MCP - Servidor de Protocolo de Contexto de Modelo para integração com IA (Claude, etc.)
  • 📊 Análises e Visualização - Estatísticas abrangentes com gráficos ASCII

Fonte de Dados

O GranolaMCP opera inteiramente em arquivos de cache locais - ele lê os dados das reuniões diretamente do arquivo de cache local do Granola (cache-v3.json) sem fazer nenhuma chamada de API aos servidores do Granola. Essa abordagem oferece:

  • 🔌 Sem Dependência de Rede - Funciona completamente offline
  • ⚡ Acesso Rápido - Acesso direto ao sistema de arquivos sem limites de taxa de API
  • 🔒 Foco em Privacidade - Seus dados de reunião nunca saem da sua máquina
  • 🛡️ Sem Autenticação - Não é necessário gerenciar chaves de API ou tokens

Abordagem Alternativa Disponível: Embora não implementada nesta biblioteca, é tecnicamente possível extrair tokens de acesso do arquivo de configuração supabase.json do Granola e se comunicar diretamente com a API do Granola. No entanto, a abordagem baseada em cache oferece melhor desempenho, privacidade e confiabilidade para a maioria dos casos de uso.

✨ Recursos Principais

Acesso a Dados Principais

  • 🔍 Análise JSON Inteligente - Lida com a estrutura complexa de JSON duplo do cache do Granola
  • 📝 Extração de Resumos de IA - Separa resumos gerados por IA de notas humanas
  • 💬 Acesso Completo a Transcrições - Transcrições completas com identificação de falantes e tempo
  • 📁 Organização por Pastas - Organização de reuniões por pastas (OPSWAT, Mozilla, Pessoal, etc.)
  • 🕐 Cálculo Preciso de Duração - Duração real da reunião a partir do tempo da transcrição
  • 🏷️ Metadados Ricos - Participantes, timestamps e contexto da reunião

Interface CLI Avançada

  • 🎯 Filtragem Inteligente - Filtre por data, participante, título ou pasta
  • 📊 Exibição em Tabela - Tabelas limpas mostrando contagens de palavras de transcrição/resumo
  • 🔍 Busca Inteligente - Busque em títulos, conteúdo e participantes
  • 📈 Painel de Análises - Frequência de reuniões, padrões de duração e tendências
  • 🎨 Saída Bonita - Exibições de terminal formatadas e codificadas por cores
  • 📄 Capacidades de Exportação - Exporte para markdown com formatação completa

Servidor MCP para Integração com IA

  • 🤖 8 Ferramentas Abrangentes - Acesso completo aos dados de reuniões para assistentes de IA
  • 🔌 Integração com Claude Desktop - Configuração pronta para uso com Claude
  • 📡 Protocolo JSON-RPC - Implementação padrão do protocolo MCP
  • ⚡ Acesso em Tempo Real - Acesso ao vivo aos seus dados de reuniões mais recentes
  • 🛡️ Tratamento Robusto de Erros - Tratamento gracioso de dados ausentes e erros

Recursos Prontos para Empresas

  • 🐍 Zero Dependências - Apenas biblioteca padrão pura do Python
  • ⚙️ Configuração Flexível - Variáveis de ambiente, arquivos .env, argumentos de CLI
  • 🕐 Ciente de Fuso Horário - Conversão adequada de UTC para fuso horário local
  • 📅 Análise Flexível de Datas - Datas relativas (3d, 24h, 1w) e absolutas
  • 🎯 Pronto para Produção - Tratamento abrangente de erros e registro de logs

Instalação

# 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

Início Rápido

1. Configuração

Copie o arquivo de configuração de exemplo e atualize o caminho do cache:

cp .env.example .env

Edite .env para definir o caminho do arquivo de cache do 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. Exemplos de Análise de Datas

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. Conversão de Fuso Horário

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 da CLI

A CLI fornece comandos poderosos para explorar e analisar dados de reuniões com recursos avançados:

Listar Reuniões com Exibição Rica

# 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

Recursos da Exibição em Tabela:

  • ID da reunião (abreviado para legibilidade)
  • Título com truncamento inteligente
  • Data e hora no fuso horário local
  • Duração precisa a partir do tempo da transcrição
  • Contagem de palavras da transcrição (formato 6,0k para números grandes)
  • Contagem de palavras do resumo de IA (a partir de resumos extraídos)
  • Organização por pastas (Mozilla, OPSWAT, Pessoal, etc.)

Mostrar Detalhes da Reunião

# 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

Recursos da Exibição da Reunião:

  • Indicadores claros de disponibilidade (Resumo de IA: Disponível/Não disponível)
  • Resumos de IA separados de notas humanas
  • Transcrições completas com identificação de falantes
  • Metadados ricos com conversão adequada de fuso horário
  • Listas de participantes e tags

Exportar Reuniões

# 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

Painel de Estatísticas e Análises

# 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

Coletar Suas Próprias Palavras para Treinamento 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

Recursos Principais:

  • Separação de Falantes: Filtra automaticamente suas palavras (fonte do microfone) do que você ouviu (fonte do sistema)
  • Organização Diária: Cria arquivos YYYY-MM-DD.txt separados para cada dia
  • Pronto para LLM: Formato perfeito para criar conjuntos de dados de treinamento a partir da sua própria fala
  • Filtragem Flexível: Intervalos de datas, contagens mínimas de palavras, metadados opcionais
  • Gerenciamento de Arquivos: Substitui com segurança arquivos existentes com conteúdo idêntico

🤖 Servidor MCP para Integração com IA

Inicie o servidor MCP para integrar com assistentes de IA como o 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"

Integração com Claude Desktop

Adicione ao seu ~/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"
      }
    }
  }
}

Ferramentas MCP Disponíveis

O servidor fornece 10 ferramentas abrangentes:

  1. get_recent_meetings - Obtenha as X reuniões mais recentes (retrocede o quanto for necessário)
  2. list_meetings - Lista simples de reuniões com filtros de data (padrão: últimos 3 dias)
  3. search_meetings - Busca avançada com filtros de texto, participante e data
  4. get_meeting - Detalhes completos da reunião com metadados
  5. get_transcript - Transcrição completa com identificação de falantes
  6. get_meeting_notes - Resumos estruturados de IA e notas humanas
  7. list_participants - Análise de participantes com histórico de reuniões
  8. get_statistics - Gera análises (resumo, frequência, duração, padrões)
  9. export_meeting - Exporta reuniões em formato markdown
  10. analyze_patterns - Analisa padrões e tendências de reuniões

Exemplos de Uso do 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"
  }
}

Estrutura do Projeto

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 ou superior
  • Sem dependências externas (usa apenas a biblioteca padrão do Python)

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Arquitetura

Consulte ARCHITECTURE.md para documentação detalhada da arquitetura.

Roadmap

Consulte ROADMAP.md para o roadmap de desenvolvimento e planos futuros.