Notion ReadOnly MCP Server

Notion ReadOnly MCP Server

Este projeto implementa um servidor MCP otimizado e somente leitura para a API do Notion, focado em desempenho e eficiência para que assistentes de IA possam consultar e recuperar conteúdo do Notion.

Principais Melhorias

• Design Somente Leitura: Focado exclusivamente em operações de recuperação de dados, garantindo acesso seguro ao conteúdo do Notion.
• Conjunto de Ferramentas Minimizado: Reduziu o número de ferramentas expostas da API do Notion de 15+ para apenas 6 essenciais para análise de documentos.
• Processamento Paralelo: Desempenho aprimorado com implementação de requisições assíncronas e paralelas para recuperar blocos de conteúdo, reduzindo significativamente os tempos de resposta.
• Acesso Estendido a Bancos de Dados: Adicionado suporte para operações de recuperação de bancos de dados, propriedades de páginas e comentários.
• Otimizado para Assistentes de IA: A redução significativa no número de ferramentas resolve o problema de "muitas ferramentas podem degradar o desempenho" em assistentes de IA como o Cursor, que limita os modelos a aproximadamente 40 ferramentas.

Comparação de Ferramentas

Esta implementação somente leitura expõe muito menos ferramentas em comparação com a integração padrão da API do Notion, melhorando o desempenho e a compatibilidade com assistentes de IA:

O conjunto reduzido de ferramentas ajuda a permanecer dentro dos limites recomendados para um desempenho ideal do assistente de IA, ao mesmo tempo em que fornece todas as funcionalidades essenciais.

Instalação

1. Configurando a Integração no Notion:

Acesse https://www.notion.so/profile/integrations e crie uma nova integração interna ou selecione uma existente.

Embora limitemos o escopo da API do Notion exposta a operações somente leitura, há um risco não nulo para os dados do espaço de trabalho ao expô-los a LLMs. Usuários preocupados com segurança podem querer configurar ainda mais as Capacidades da Integração.

Por exemplo, você pode criar um token de integração somente leitura dando apenas acesso de "Leitura de conteúdo" na aba "Configuração":

2. Adicionando a configuração do MCP ao seu cliente:

Usando npm:

Adicione o seguinte ao seu .cursor/mcp.json ou claude_desktop_config.json (macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "notion-readonly-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"
      }
    }
  }
}

Usando Docker:

Adicione o seguinte ao seu .cursor/mcp.json ou claude_desktop_config.json:

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "taewoong1378/notion-readonly-mcp-server"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

Não se esqueça de substituir ntn_**** pelo seu segredo de integração. Encontre-o na aba de configuração da sua integração.

3. Conectando conteúdo à integração:

Garanta que as páginas e bancos de dados relevantes estejam conectados à sua integração.

Para fazer isso, visite a página, clique nos 3 pontos e selecione "Conectar à integração".

Ferramentas Disponíveis

Este servidor otimizado expõe apenas as ferramentas essenciais da API do Notion em modo somente leitura:

• API-retrieve-a-page: Obter informações da página
• API-get-block-children: Obter blocos de conteúdo da página (com processamento paralelo)
• API-retrieve-a-block: Obter detalhes sobre um bloco específico
• API-retrieve-a-database: Obter informações do banco de dados
• API-retrieve-a-comment: Obter comentários em uma página ou bloco
• API-retrieve-a-page-property: Obter informações específicas de propriedade de uma página
• API-get-one-pager: NOVO! Recuperar recursivamente uma página completa do Notion com todos os seus blocos, bancos de dados e conteúdo relacionado em uma única chamada

Ao limitar a essas 7 ferramentas essenciais (em comparação com 15+ na implementação padrão), garantimos:

1. Melhor desempenho em assistentes de IA como Cursor e Claude que têm limitações no número de ferramentas
2. Carga cognitiva reduzida para modelos de IA ao escolher ferramentas apropriadas
3. Tempos de resposta mais rápidos com menos opções de API para considerar
4. Segurança aprimorada através da minimização da superfície da API

Exploração Automática de Conteúdo

A nova ferramenta API-get-one-pager fornece uma maneira poderosa de explorar páginas do Notion sem exigir múltiplas chamadas de API:

• Recuperação recursiva: Percorre automaticamente toda a estrutura da página, incluindo blocos aninhados
• Processamento paralelo: Busca múltiplos blocos e seus filhos simultaneamente para máximo desempenho
• Cache inteligente: Armazena dados recuperados para minimizar chamadas de API redundantes
• Conteúdo abrangente: Inclui páginas, blocos, bancos de dados, comentários e informações detalhadas de propriedades
• Profundidade personalizável: Controle o nível de recursão para equilibrar entre detalhes e desempenho

Usando a ferramenta One Pager

{
  "page_id": "YOUR_PAGE_ID",
  "maxDepth": 5,               // Optional: Maximum recursion depth (default: 5)
  "includeDatabases": true,    // Optional: Include linked databases (default: true)
  "includeComments": true,     // Optional: Include comments (default: true)
  "includeProperties": true    // Optional: Include detailed page properties (default: true)
}

Essa capacidade de exploração automática é especialmente útil para assistentes de IA que precisam entender o conteúdo completo de uma página do Notion sem fazer dezenas de chamadas de API separadas, resultando em respostas muito mais rápidas e eficientes.

Processamento Assíncrono

O servidor implementa técnicas avançadas de processamento paralelo para lidar com documentos grandes do Notion:

• Várias requisições são agrupadas e processadas simultaneamente
• A paginação é tratada automaticamente para blocos filhos
• Os resultados são agregados eficientemente antes de serem retornados
• O registro em console fornece visibilidade sobre o processo sem afetar o formato da resposta

Exemplos

1. Usando a seguinte instrução:

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

A IA recuperará os detalhes da página eficientemente com processamento paralelo do conteúdo dos blocos.

2. Usando informações do banco de dados:

Get the structure of database 8a6b35e6e67f802fa7e1d27686f017f2

Desenvolvimento

Build:

pnpm build

Execução:

pnpm dev

Licença

MIT

Benefícios de Desempenho para Assistentes de IA

Assistentes de IA modernos como Cursor e Claude têm limitações no número de ferramentas que podem lidar efetivamente:

• A maioria dos modelos pode não respeitar mais de 40 ferramentas no total
• Muitas ferramentas podem degradar o desempenho geral e as capacidades de raciocínio
• Conjuntos de ferramentas complexos aumentam a latência de resposta e a dificuldade de tomada de decisão

Esta implementação somente leitura reduz deliberadamente a superfície da API do Notion para superar essas limitações, preservando todas as funcionalidades essenciais. O resultado é:

• Respostas mais rápidas e confiáveis dos assistentes de IA
• Precisão melhorada ao interagir com conteúdo do Notion
• Melhor desempenho geral através de um design de API focado