notion-automation-suite

LucasBiason/notion-automation-suite

3.2

If you are the rightful owner of notion-automation-suite and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Notion MCP Server is a streamlined server designed to automate Notion workflows using the Model Context Protocol, encapsulating specific business rules and exposing tools compatible with Cursor and other MCP agents.

Notion MCP Server

Servidor MCP enxuto para automatizar fluxos do Notion via Model Context Protocol. Ele encapsula regras de negócio específicas das bases e expõe tools compatíveis com Cursor e outros agentes MCP.

Visão geral

  • Domínios suportados: trabalho, estudos, pessoal e conteúdo.
  • Regras embutidas: validação de título, status, relações, períodos e horários antes da chamada HTTP.
  • Tecnologias: Python 3.10+, httpx, tenacity, structlog, pytest.
  • Integração: execução via stdio (notion-mcp-server) e container Docker pronto para uso.

Estrutura do repositório

notion-automation-suite/
├── src/
│   ├── custom/        # Regras por domínio (Work, Studies, Personal, Youtuber)
│   ├── services/      # Wrapper da API do Notion
│   ├── tools/         # Definição das tools MCP
│   ├── runtime/       # Inicialização, carga de env e loop stdio
│   ├── utils/         # Constantes, validações e formatadores
│   ├── exceptions/    # Exceções específicas do serviço
│   └── notion_mcp.py  # Compatibilidade com imports antigos
├── tests/
│   ├── custom/
│   ├── services/
│   ├── tools/
│   └── conftest.py
├── docs/
│   ├── README.md
│   └── mcp/           # Documentação detalhada
└── pyproject.toml

Configuração do ambiente

  1. Clonar o repositório:

    git clone https://github.com/LucasBiason/notion-automation-suite.git
cd notion-automation-suite

  2. Criar ambiente virtual e instalar dependências:

    python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

  3. Configurar variáveis do Notion:

    • Copie config/env.example (caso exista) para config/.env ou defina as variáveis manualmente.
    • Campos esperados:
      • NOTION_API_TOKEN
      • NOTION_WORK_DATABASE_ID
      • NOTION_STUDIES_DATABASE_ID
      • NOTION_PERSONAL_DATABASE_ID
      • NOTION_YOUTUBER_DATABASE_ID

  4. Executar o servidor localmente:

    notion-mcp-server

    O comando carrega o ambiente, inicializa logging e disponibiliza o loop stdio.

Execução via Docker

docker build -t notion-mcp-server .
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

Testes

  • Execute make test para rodar a suíte (unit + integration).
  • ruff, mypy e demais ferramentas podem ser disparadas via make lint/make type caso configurados.

Documentação

A documentação completa está em e inclui:

  • Visão geral e objetivos (docs/mcp/README.md)
  • Arquitetura detalhada (docs/mcp/ARCHITECTURE.md)
  • Referência de API (docs/mcp/API.md)
  • Guia de configuração no Cursor (docs/mcp/SETUP_CURSOR.md)
  • Exemplos práticos (docs/mcp/EXAMPLES.md)
  • Roadmap e próximos passos (docs/mcp/ROADMAP.md)

Integração com agentes

Este repositório expõe apenas o MCP. Qualquer coordenação de agentes e configurações específicas deve acontecer em , que consome este servidor como backend de automação.

Manutenção

  • Ajuste regras de negócio sempre adicionando testes correspondentes.
  • Atualize a documentação após mudanças relevantes.
  • Mantenha os tokens e IDs fora do versionamento (config/private/ permanece ignorado).