CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

notion-integration

Integração completa com Notion usando MCP customizado (notion-automation-suite)

Quality

60%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/integration/notion/SKILL.md
SKILL.md
Quality
Evals
Security

Notion Integration

Integração completa com Notion usando MCP customizado notion-automation-suite.

Última Atualização: 2026-01-27
MCP Server: notion-automation-suite
Localização: notion-automation-suite (Infraestrutura)


⚠️ REGRA: Contexto dos cards por projeto

Tudo que envolve cards no Notion deve ficar no contexto do projeto respectivo.

  • Estudos / Cursos: Cards de cursos (ex.: Fast Master, FIAP, IA Master) pertencem ao workspace Estudos. O conteúdo e resumos para atualizar esses cards ficam em paths como:
    • Fast Master (PyCodeBR): Estudos/Apostilas e Materiais de Cursos/[PyCodeBR] Fast Master/Modulo-01-Introducao/conteudo-e-resumos.md
    • Outros cursos: Estudos/Apostilas e Materiais de Cursos/[Nome do Curso]/... ou Estudos/Resumos de Cursos/...
  • Trabalho: Cards de trabalho no contexto do workspace Trabalho/Projetos correspondentes.
  • Pessoal / YouTube: No contexto do projeto onde o conteúdo ou série está definido.

IDs dos cards (page_id): Sempre usar os IDs armazenados no contexto privado do projeto, nunca na skill pública (informação sigilosa).

⚠️ Regra: contexto privado (não colocar dados sigilosos na skill)

  • Page_ids, URLs de cards e dados de cursos (ex.: MBA, Fast Master, card Threat Modeling AI) ficam apenas no contexto privado da frente/projeto:
    • Estudos – Estação Pessoal / Notion: config/studies/estacao-pessoal/ (NOTION_CARDS_EXISTENTES_ESTACAO_PESSOAL.md, checklist, roadmap).
    • Estudos – Curso específico: config/studies/catalogo/[fonte]/ (ex.: fullcycle/mba-engenharia-software-ia.md, pycodebr).
    • Projetos em andamento: config/studies/projetos/em-andamento/[projeto]/ (ex.: threat-modeling-ai).
  • Nunca colocar URLs ou page_ids de Notion na skill pública. Ao operar MCP Notion para um curso: ler o page_id no arquivo do projeto (estacao-pessoal ou catalogo do curso).
  • Captura de aulas/módulos: Preferir Playwright (MCP) na plataforma (ex.: Full Cycle) e depois criar subitens via MCP Notion usando o parent_id lido do contexto privado.

Ao criar ou atualizar cards de um curso/formação:

  1. Ler os page_id do arquivo do projeto (ex.: seção "IDs no Notion" em conteudo-e-resumos.md).
  2. Usar o conteúdo e os "Dados para atualização dos cards" do arquivo do projeto correto.
  3. Não duplicar informações em outros workspaces; não gravar dados de um curso em base ou contexto de outro projeto.

Quando Usar

Aplicar esta skill quando:

  • Criar, atualizar ou consultar cards no Notion
  • Trabalhar com projetos de trabalho, estudos, pessoal ou YouTube
  • Usar o MCP customizado notion-automation-suite
  • Precisar seguir regras específicas de organização do Notion

⚠️ REGRA CRÍTICA: Execução Completa

QUANDO O USUÁRIO PEDIR PARA CRIAR/ATUALIZAR CARDS NO NOTION, EXECUTAR ATÉ O FINAL.

O que significa "até o final":

  • ✅ Criar TODOS os cards solicitados (não apenas gerar instruções)
  • ✅ Criar hierarquia completa (curso → fases → aulas, projeto → tarefas, etc.)
  • ✅ Usar o MCP diretamente para criar os cards
  • ✅ NÃO apenas gerar scripts ou instruções
  • ✅ NÃO parar no meio - completar toda a estrutura solicitada

Exemplos:

❌ ERRADO:

  • Gerar apenas instruções de como criar
  • Criar apenas o curso base e parar
  • Deixar para o usuário executar

✅ CORRETO:

  • Criar curso base → criar todas as fases → criar todas as aulas
  • Criar projeto → criar todas as tarefas vinculadas
  • Executar todos os comandos MCP necessários até completar

MCP Customizado: notion-automation-suite

Configuração

Localização: notion-automation-suite (Infraestrutura)

Como usar no Cursor: Configurar o servidor MCP no Cursor (Settings → MCP) apontando para o notion-automation-suite (stdio ou Docker). Ver docs/mcp/SETUP_CURSOR.md no repositório do MCP. As tools só ficam disponíveis no Composer quando o MCP está conectado ao workspace (ex.: Infraestrutura).

Configuração:

  • Documentação: notion-automation-suite/config/README.md
  • Template: notion-automation-suite/config/defaults/env.example
  • Arquivo real: notion-automation-suite/config/.env ou config/notion-mcp.env (gitignored)

Variáveis de Ambiente Obrigatórias:

  • NOTION_API_TOKEN - Token da API do Notion
  • NOTION_WORK_DATABASE_ID - ID da base de trabalho
  • NOTION_STUDIES_DATABASE_ID - ID da base de estudos
  • NOTION_PERSONAL_DATABASE_ID - ID da base pessoal
  • NOTION_YOUTUBER_DATABASE_ID - ID da base YouTube

⚠️ IMPORTANTE: Os IDs das databases ficam no projeto do MCP via variáveis de ambiente. O cursor-multiagent-system não deve ter acesso direto a esses IDs, apenas usar o MCP construído.

Execução:

# Via stdio
notion-mcp-server

# Via Docker
docker run -i --rm \
  -e NOTION_API_TOKEN=secret_xxx \
  -e NOTION_WORK_DATABASE_ID=... \
  -e NOTION_STUDIES_DATABASE_ID=... \
  -e NOTION_PERSONAL_DATABASE_ID=... \
  -e NOTION_YOUTUBER_DATABASE_ID=... \
  notion-mcp-server

Tools Disponíveis

O MCP expõe tools especializadas por domínio:

Work (Trabalho)

  • work_create_project - Criar projeto de trabalho
  • work_create_sprint - Criar sprint com subtarefas
  • work_create_task - Criar tarefa/subitem vinculado
  • work_update_status - Atualizar status
  • work_assign_project - Alterar projeto vinculado
  • work_query_projects - Consultar cards por filtros

Studies (Estudos)

  • study_create_course - Criar curso (apenas data, sem horário)
  • study_create_course_complete - Criar curso completo com fases/seções/aulas
  • study_create_phase - Criar fase vinculada a curso
  • study_create_section - Criar seção vinculada
  • study_create_class - Criar aula (com horário, respeita regras 19h-21h)
  • study_reschedule_section - Reagendar aulas de uma seção
  • study_query_schedule - Consultar aulas por período/status
  • study_update_card - Atualizar card de estudo (status, período, descrição/resumo). Uso: marcar aula/módulo como Concluído, preencher resumo e período. Status Studies: "Concluido" (sem acento).

Personal (Pessoal)

  • personal_create_task - Criar tarefa pessoal
  • personal_create_subtask - Criar subtarefa vinculada
  • personal_use_template - Usar template genérico (ex: weekly_planning)
  • personal_create_medical_appointment - Criar consulta médica

Youtuber (YouTube)

  • youtuber_create_series - Criar série completa com episódios automáticos
  • youtuber_create_episode - Criar episódio vinculado a série
  • youtuber_schedule_recordings - Gerar episódios sequenciais
  • youtuber_update_episode_status - Atualizar status do episódio
  • youtuber_reschedule_episode - Reagendar gravação/publicação
  • youtuber_query_schedule - Consultar episódios por filtros

Estrutura das 4 Bases

1. BASE TRABALHO (WORK)

Campo de Título: Nome do projeto
Campo de Relação: item principal
Uso: Projetos profissionais (ExpenseIQ, HubTravel, etc.)

Propriedades Principais

  • Nome do projeto (title) - Título do card
  • Status (status) - Estado atual
  • Cliente (select) - Astracode, Pessoal, FIAP
  • Projeto (select) - ExpenseIQ, HubTravel, Avulso
  • Prioridade (select) - Baixa, Normal, Média, Alta, Urgente
  • Periodo (date) - Data/hora de execução
  • item principal (relation) - Vínculo com card pai

Status Disponíveis

  • Não iniciado (padrão)
  • Em Andamento
  • Em Revisão
  • Concluído
  • Pausado
  • Cancelado

Valores Padrão

  • cliente: "Astracode" (padrão para trabalho profissional)
  • projeto: "Avulso" (quando não especificado)
  • prioridade: "Normal"
  • status: "Não iniciado"

Exemplo de Uso (MCP)

# Via MCP tool
work_create_project(
    title="Implementar Feature X",
    cliente="Astracode",
    projeto="ExpenseIQ",
    prioridade="Alta",
    icon="🚀"
)

2. BASE PESSOAL (PERSONAL)

Campo de Título: Nome da tarefa
Campo de Relação: tarefa principal
Campo de Data: Data (não Periodo)
Uso: Tarefas pessoais, organização, hábitos

Propriedades Principais

  • Nome da tarefa (title) - Título da tarefa
  • Status (status) - Estado atual
  • Atividade (select) - Tipo de atividade
  • Data (date) - Data da tarefa (campo específico)
  • Descrição (rich_text) - Descrição detalhada
  • tarefa principal (relation) - Tarefa principal (pai)

Status Disponíveis

  • Não iniciado (padrão)
  • Em Andamento
  • Concluído
  • Cancelado

Atividades Comuns

  • Desenvolvimento
  • Organização
  • Estudo
  • Teste
  • Planejamento
  • Financeiro
  • Saúde
  • Lazer

Exemplo de Uso (MCP)

# Via MCP tool
personal_create_task(
    title="Organizar Documentos",
    atividade="Organização",
    data={
        "start": "2025-10-15T19:00:00-03:00",
        "end": "2025-10-15T20:00:00-03:00"
    },
    icon="👤"
)

3. BASE CURSOS (STUDIES)

Campo de Título: Project name
Campo de Relação: Parent item
Campo de Data: Período (com acento)
Uso: Cursos, formações, aulas, estudos

Propriedades Principais

  • Project name (title) - Nome do curso/aula
  • Status (status) - Estado atual
  • Categorias (multi_select) - Tags do curso
  • Prioridade (select) - Nível de prioridade
  • Período (date) - Quando estudar
  • Tempo Total (rich_text) - Duração estimada (HH:MM:SS)
  • Parent item (relation) - Item pai (curso/seção)

Status Disponíveis

  • Não Adquirido
  • Para Fazer (padrão)
  • Em Revisão
  • Em Pausa
  • Em Andamento
  • Descontinuado
  • Concluido (sem acento)

Estrutura Hierárquica

Formação/Curso (sem horário)
├── Fase/Bloco (sem horário)
│   ├── Seção/Módulo (sem horário)
│   │   ├── Aula 1 (COM horário 19:00-21:00)
│   │   ├── Aula 2 (COM horário 19:00-21:00)
│   │   └── Aula 3 (COM horário 19:00-21:00)

Regra de Horários

  • Aulas (nível mais baixo): COM horário específico (19:00-21:00)
  • Seções/Módulos: SEM horário (apenas data)
  • Cursos/Formações: SEM horário (apenas data)

Horários de Estudo

  • Segunda, Quarta, Quinta, Sexta: 19:00-21:00
  • Terça: 19:30-21:00 (após tratamento médico)
  • LIMITE MÁXIMO: 21:00 (NUNCA ultrapassar)
  • Se passar das 21:00: Mover aula para próximo dia útil às 19:00

Exemplo de Uso (MCP)

# Curso (sem horário)
study_create_course(
    title="FIAP IA para Devs",
    categorias=["FIAP", "Inteligência Artificial"],
    periodo={"start": "2025-10-16", "end": "2025-12-15"},
    tempo_total="40:00:00",
    icon="🎓"
)

# Aula (com horário)
study_create_class(
    parent_id=section_id,
    title="Aula 1: Introdução",
    start_time="2025-10-16T19:00:00-03:00",
    duration_minutes=120,  # 2 horas (19:00-21:00)
    icon="🎯"
)

4. BASE YOUTUBE (YOUTUBER)

Campo de Título: Nome do projeto
Campo de Relação: item principal
Uso: Séries de jogos e episódios do canal

Propriedades Principais

  • Nome do projeto (title) - Nome da série/episódio
  • Status (status) - Estado atual
  • Periodo (date) - Data/hora de GRAVAÇÃO
  • Data de Lançamento (date) - Data/hora de PUBLICAÇÃO
  • Resumo do Episodio (rich_text) - Sinopse do episódio/série
  • Link do Video (url) - URL do vídeo publicado
  • item principal (relation) - Série (para episódios)

Status Disponíveis

  • Para Gravar
  • Não iniciado (padrão)
  • Gravando
  • Para Edição
  • Editando
  • Editado
  • Publicado
  • Concluído

Diferença Entre Campos de Data

Periodo (Data de Gravação):

  • Quando o episódio será GRAVADO
  • Data e hora reais de trabalho
  • Exemplo: 2025-10-16T21:00:00-03:00 até 2025-10-16T23:30:00-03:00

Data de Lançamento (Publicação):

  • Quando o episódio será PUBLICADO
  • Data e hora que ficará público no YouTube
  • Exemplo: 2025-10-17T12:00:00-03:00

Estrutura Hierárquica

Série Principal (sem Data de Lançamento)
  └─ Periodo: início da gravação do 1º ep → fim da gravação do último ep
├── Episódio 01 (com Periodo E Data de Lançamento)
├── Episódio 02 (com Periodo E Data de Lançamento)
└── Episódio 03 (com Periodo E Data de Lançamento)

Regras Especiais

  • Série: Tem Periodo (gravação), NÃO tem Data de Lançamento
  • Episódios: Tem AMBOS (Periodo e Data de Lançamento)
  • Primeiro episódio: Deve ter sinopse da série em Resumo do Episodio

Exemplo de Uso (MCP)

# Série
youtuber_create_series(
    title="The Legend of Heroes",
    sinopse="Série completa sobre...",
    total_episodes=10,
    first_recording="2025-10-16T21:00:00-03:00",
    recording_interval_days=1,
    publication_hour=12,
    icon="🎮"
)

# Episódio
youtuber_create_episode(
    parent_id=series_id,
    episode_number=1,
    title="Episódio 01",
    recording_date="2025-10-16T21:00:00-03:00",
    publication_date="2025-10-17T12:00:00-03:00",
    resumo_episodio="Sinopse da série completa...",  # Obrigatório no ep 1
    icon="📺"
)

Regras Críticas

1. Timezone - OBRIGATÓRIO GMT-3

SEMPRE usar GMT-3 (São Paulo)
NUNCA usar UTC

Formatos Corretos

Com Horário:

'start': '2025-10-16T19:00:00-03:00'
'end': '2025-10-16T21:00:00-03:00'

Sem Horário (apenas data):

'start': '2025-10-16'
'end': '2025-10-30'

Código Python

from datetime import datetime, timezone, timedelta

SAO_PAULO_TZ = timezone(timedelta(hours=-3))
dt = datetime(2025, 10, 16, 19, 0, 0, tzinfo=SAO_PAULO_TZ)
data_notion = dt.isoformat()  # '2025-10-16T19:00:00-03:00'

2. Ícones e Emojis

Emojis SEMPRE como ícone da página
NUNCA no título do card

Formato Correto

# ✅ CORRETO
{
    "icon": {"emoji": "🎓"},  # Ícone aqui
    "properties": {
        "Project name": {
            "title": [{"text": {"content": "Meu Curso"}}]  # Sem emoji
        }
    }
}

# ❌ ERRADO
"title": [{"text": {"content": "🎓 Meu Curso"}}]

Emojis Recomendados por Base

WORK:

  • Projetos: 🚀, 💼, 🏢
  • Sub-itens: 📋, ✅, 🔧

PERSONAL:

  • Tarefas: 👤, 📝, 🎯
  • Subtarefas: ✅, 📌, ⚡

STUDIES:

  • Cursos: 🎓, 📚, 🎯
  • Fases: 📖, 📑
  • Seções: 📑, 📂
  • Aulas: 🎯, 📝, 💡

YOUTUBER:

  • Séries: 🎬, 🎮, 📺
  • Episódios: 📺, 🎥, ▶️

3. Hierarquias e Vínculos

Sub-itens DEVEM ter campo de relação preenchido

Campos de Relação por Base

BasePara Criar Sub-itemCampo a UsarValor
WORKSub-item de projetoitem_principalID do projeto pai
PERSONALSubtarefatarefa_principalID da tarefa pai
STUDIESAula de cursoparent_itemID do curso/seção
YOUTUBEREpisódio de sérieitem_principalID da série

Exemplo de Hierarquia (WORK)

# 1. Criar projeto principal
project_id = work_create_project(
    title="Projeto Principal",
    cliente="Astracode",
    projeto="ExpenseIQ"
)

# 2. Criar sub-item LINKADO
task_id = work_create_task(
    parent_id=project_id,  # ← VÍNCULO
    title="Sub-item 1"
)

4. Campos de Data por Base

BaseCampo de DataFormato
WORKPeriodoCom horário (ex: 2025-10-16T09:00:00-03:00)
PERSONALDataCom horário (ex: 2025-10-16T19:00:00-03:00)
STUDIESPeríodo (com acento)Sem horário para cursos/seções, com horário para aulas
YOUTUBERPeriodo + Data de LançamentoAmbos com horário

5. Validações Obrigatórias

Antes de criar qualquer card:

  1. ✅ Verificar título (sem emojis)
  2. ✅ Verificar status válido para a base
  3. ✅ Verificar timezone GMT-3 em todas as datas
  4. ✅ Verificar campo de relação correto (se sub-item)
  5. ✅ Verificar horários apenas onde necessário (aulas, episódios)
  6. ✅ Verificar duplicatas (título + data + cliente/projeto)

Mapeamento de Campos

Como Passar Dados para MCP Tools

BaseVocê PassaVira no Notion
WORKtitleNome do projeto
clienteCliente
projetoProjeto
prioridadePrioridade
periodoPeriodo
item_principalitem principal
PERSONALtitleNome da tarefa
atividadeAtividade
dataData
tarefa_principaltarefa principal
STUDIEStitleProject name
categoriasCategorias
prioridadePrioridade
tempo_totalTempo Total
periodoPeríodo
parent_itemParent item
YOUTUBERtitleNome do projeto
periodoPeriodo
data_lancamentoData de Lançamento
resumo_episodioResumo do Episodio
item_principalitem principal

Exemplos Práticos

Criar Projeto de Trabalho com Subtarefas

# Via MCP tool
project = work_create_project(
    title="Implementar Feature X",
    cliente="Astracode",
    projeto="ExpenseIQ",
    prioridade="Alta",
    icon="🚀"
)

# Criar subtarefas
for task_title in ["Mapear requisitos", "Implementar", "Testar"]:
    work_create_task(
        parent_id=project["id"],
        title=task_title,
        icon="📋"
    )

Criar Curso Completo com Aulas

# Curso (sem horário)
course = study_create_course(
    title="FIAP IA para Devs - Fase 5",
    categorias=["FIAP", "Inteligência Artificial"],
    periodo={"start": "2025-01-15", "end": "2025-03-31"},
    tempo_total="80:00:00",
    icon="🎓"
)

# Seção (sem horário)
section = study_create_section(
    parent_id=course["id"],
    title="Seção 1: Fundamentos",
    periodo={"start": "2025-01-15", "end": "2025-01-31"},
    tempo_total="16:00:00",
    icon="📑"
)

# Aula (com horário, respeita 19h-21h)
class_card = study_create_class(
    parent_id=section["id"],
    title="Aula 1: Introdução",
    start_time="2025-01-15T19:00:00-03:00",
    duration_minutes=120,  # 2 horas (19:00-21:00)
    icon="🎯"
)

Criar Série YouTube com Episódios

# Série completa (gera episódios automaticamente)
series = youtuber_create_series(
    title="The Legend of Heroes",
    sinopse="Série completa sobre...",
    total_episodes=10,
    first_recording="2025-10-16T21:00:00-03:00",
    recording_interval_days=1,
    publication_hour=12,
    icon="🎮"
)

# Ou criar episódio individual
episode = youtuber_create_episode(
    parent_id=series["id"],
    episode_number=1,
    title="Episódio 01",
    recording_date="2025-10-16T21:00:00-03:00",
    publication_date="2025-10-17T12:00:00-03:00",
    resumo_episodio="Sinopse da série completa...",  # Obrigatório no ep 1
    icon="📺"
)

Checklist de Validação

Antes de Criar Card

  • Base correta identificada (WORK, PERSONAL, STUDIES, YOUTUBER)
  • Campo de título preenchido (sem emojis)
  • Ícone definido (emoji separado)
  • Status válido para a base
  • Timezone GMT-3 em todas as datas
  • Se for sub-item: ID do pai conhecido e campo de relação correto
  • Se STUDIES: Horário apenas em aulas (nível mais baixo)
  • Se YOUTUBER: Série SEM data_lancamento, Episódios COM data_lancamento
  • Verificado duplicatas (título + data + cliente/projeto)

Erros Comuns

1. Status Inválido

# ❌ ERRADO - YOUTUBER
'status': 'Para Fazer'  # Não existe nesta base

# ✅ CORRETO - YOUTUBER
'status': 'Não iniciado'

2. Campo de Data Errado

# ❌ ERRADO - PERSONAL
'periodo': {...}  # Campo não existe

# ✅ CORRETO - PERSONAL
'data': {...}  # Campo correto

3. Campo de Relação Errado

# ❌ ERRADO - STUDIES
'item_principal': 'id'  # Campo errado

# ✅ CORRETO - STUDIES
'parent_item': 'id'  # Campo correto

4. Emoji no Título

# ❌ ERRADO
'title': '🎓 Meu Curso'

# ✅ CORRETO
'title': 'Meu Curso', 'icon': '🎓'

5. Horário em Card Errado

# ❌ ERRADO - Seção de curso
'periodo': {'start': '2025-10-16T19:00:00-03:00'}  # Não deve ter horário

# ✅ CORRETO - Seção de curso
'periodo': {'start': '2025-10-16'}  # Apenas data

Referências

  • MCP Server: notion-automation-suite
  • Configurações Privadas: config/notion/ (compromissos, projetos e informações pessoais por frente)
  • Contexto Geral: config/CONTEXTO_GERAL.md (horários e rotina - NUNCA duplicar aqui)

Sempre usar o MCP customizado notion-automation-suite para garantir que todas as regras sejam respeitadas automaticamente.

Repository

fernandezbaptiste/cursor-multiagent-system

Path

skills/integration/notion/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.