Notion API MCP

Interaja com a API do Notion para gerenciar listas de tarefas, bancos de dados e organização de conteúdo.

GitHub
28

Documentação

Notion API MCP

Um servidor Model Context Protocol (MCP) que fornece recursos avançados de gerenciamento de listas de tarefas e organização de conteúdo através da API do Notion. O MCP permite que modelos de IA interajam com ferramentas e serviços externos, possibilitando integração perfeita com os recursos poderosos do Notion.

Visão Geral do MCP

Servidor MCP baseado em Python que permite que modelos de IA interajam com a API do Notion, fornecendo:

  • Gerenciamento de Tarefas: Crie, atualize e acompanhe tarefas com texto rico, datas de conclusão, prioridades e subtarefas aninhadas
  • Operações de Banco de Dados: Crie e gerencie bancos de dados do Notion com propriedades personalizadas, filtros e visualizações
  • Organização de Conteúdo: Estruture e formate conteúdo com suporte a Markdown, listas hierárquicas e operações de blocos
  • Integração em Tempo Real: Interação direta com o espaço de trabalho, páginas e bancos de dados do Notion através de implementação assíncrona limpa

Lista completa de recursos →

Início Rápido

# Clone and setup
git clone https://github.com/yourusername/notion-api-mcp.git
cd notion-api-mcp
uv venv && source .venv/bin/activate

# Install and configure
uv pip install -e .
cp .env.integration.template .env

# Add your Notion credentials to .env:
# NOTION_API_KEY=ntn_your_integration_token_here
# NOTION_PARENT_PAGE_ID=your_page_id_here  # For new databases
# NOTION_DATABASE_ID=your_database_id_here  # For existing databases

# Run the server
python -m notion_api_mcp

Começando

1. Criar uma Integração do Notion

  1. Acesse https://www.notion.so/my-integrations
  2. Clique em "New integration"
  3. Dê um nome à sua integração (ex.: "My MCP Integration")
  4. Selecione o espaço de trabalho onde você usará a integração
  5. Copie o "Internal Integration Token" - este será o seu NOTION_API_KEY
    • Deve começar com "ntn_"

2. Configurar o Acesso ao Notion

Você precisará de uma página pai (para criar novos bancos de dados) ou de um ID de banco de dados existente:

Opção A: Página Pai para Novos Bancos de Dados

  1. Abra o Notion no seu navegador
  2. Crie uma nova página ou abra uma existente onde deseja criar bancos de dados
  3. Clique no menu ••• no canto superior direito
  4. Selecione "Add connections" e escolha sua integração
  5. Copie o ID da página a partir da URL - é a string após a última barra e antes do ponto de interrogação
    • Exemplo: Em https://notion.so/myworkspace/123456abcdef..., o ID é 123456abcdef...
    • Este será o seu NOTION_PARENT_PAGE_ID

Opção B: Banco de Dados Existente

  1. Abra seu banco de dados existente no Notion
  2. Certifique-se de que ele está conectado à sua integração (menu ••• > Add connections)
  3. Copie o ID do banco de dados a partir da URL
    • Exemplo: Em https://notion.so/myworkspace/123456abcdef...?v=..., o ID é 123456abcdef...
    • Este será o seu NOTION_DATABASE_ID

3. Instalar o Servidor MCP

  1. Crie o ambiente virtual:
cd notion-api-mcp
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Instale as dependências:
uv pip install -e .
  1. Configure o ambiente:
cp .env.integration.template .env
  1. Edite o .env com suas credenciais do Notion:
NOTION_API_KEY=ntn_your_integration_token_here

# Choose one or both of these depending on your needs:
NOTION_PARENT_PAGE_ID=your_page_id_here  # For creating new databases
NOTION_DATABASE_ID=your_database_id_here  # For working with existing databases

4. Configurar o Claude Desktop

IMPORTANTE: Embora o servidor suporte tanto arquivos .env quanto variáveis de ambiente, o Claude Desktop especificamente requer configuração em seu arquivo de configuração para usar o MCP.

Adicione ao arquivo de configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "notion-api": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["-m", "notion_api_mcp"],
      "env": {
        "NOTION_API_KEY": "ntn_your_integration_token_here",
        
        // Choose one or both:
        "NOTION_PARENT_PAGE_ID": "your_page_id_here",
        "NOTION_DATABASE_ID": "your_database_id_here"
      }
    }
  }
}

Observação: Mesmo que você tenha um arquivo .env configurado, você deve adicionar essas variáveis de ambiente ao arquivo de configuração do Claude Desktop para que o Claude use o MCP. O arquivo .env é principalmente para desenvolvimento e testes locais.

Documentação

Desenvolvimento

O servidor utiliza recursos assíncronos modernos do Python em todo o projeto:

  • Configuração com segurança de tipos usando modelos Pydantic
  • HTTP assíncrono usando httpx para melhor desempenho
  • Integração MCP limpa para expor as capacidades do Notion
  • Limpeza adequada de recursos e tratamento de erros

Depuração

O servidor inclui registro abrangente:

  • Saída no console para desenvolvimento
  • Registro em arquivo quando executado como serviço
  • Mensagens de erro detalhadas
  • Registro de solicitações/respostas no nível de depuração

Defina PYTHONPATH para incluir a raiz do projeto ao executar diretamente:

PYTHONPATH=/path/to/project python -m notion_api_mcp

Desenvolvimento Futuro

Melhorias planejadas:

  1. Otimização de Desempenho

    • Adicionar cache de solicitações
    • Otimizar consultas ao banco de dados
    • Implementar pool de conexões

  2. Recursos Avançados

    • Suporte a vários espaços de trabalho
    • Operações em lote
    • Atualizações em tempo real
    • Recursos avançados de busca

  3. Experiência do Desenvolvedor

    • Documentação interativa da API
    • Ferramentas de linha de comando para operações comuns
    • Exemplos de código adicionais
    • Monitoramento de desempenho

  4. Melhorias de Testes

    • Benchmarks de desempenho
    • Testes de carga
    • Casos de borda adicionais
    • Testes de integração estendidos