Notion MCP

npx add-mcp 'https://mcp.notion.com/mcp'

Servidor Notion MCP

[!NOTE]

Para a melhor experiência, use Remote Notion MCP, nosso servidor MCP hospedado oficial. Este repositório é uma implementação separada de servidor MCP auto-hospedado que não é mais mantida ou suportada ativamente. Por favor, use Remote Notion MCP em vez disso. Ele é projetado especificamente para dar a agentes de IA resultados mais rápidos usando muito menos tokens.

Remote Notion MCP pode pesquisar seu workspace e aplicativos conectados semanticamente, ler e editar páginas em Markdown, e retornar apenas o contexto mais relevante. Isso significa menos tempo de espera, menos uso da janela de contexto e custos de token mais baixos. Ele também usa OAuth e respeita automaticamente as permissões existentes do Notion de cada usuário—sem tokens de API, configuração JSON, compartilhamento manual de páginas ou um servidor local para manter.

Recurso	Remote Notion MCP	Este projeto (local)
Experiência rápida e hospedada	✅	Executa e atualiza localmente
Respostas eficientes em tokens	✅	Limitado
Ferramentas poderosas adaptadas para agentes de IA	✅	Ferramentas básicas derivadas da API
Pesquisa semântica no seu workspace do Notion	✅	Apenas pesquisa por palavras-chave
Pesquisa do AI Connector em aplicativos conectados	✅	Não disponível
Leitura e edição de páginas nativas em Markdown	✅	Limitado a duas ferramentas de conteúdo de página
Configuração OAuth integrada	✅	Configuração manual de token e JSON
Respeita as permissões existentes do Notion de cada usuário	✅	Permissões de integração manuais e compartilhamento de páginas
Suporte ativo e melhorias contínuas	✅	Não suportado ativamente

Saiba mais e comece na documentação do Remote Notion MCP.

Estamos priorizando e fornecendo suporte ativo apenas para Remote Notion MCP. Como resultado:

• Podemos descontinuar este repositório de servidor MCP local no futuro.
• Issues e pull requests aqui não são monitorados ativamente.
• Por favor, não abra issues relacionadas ao MCP remoto aqui; em vez disso, entre em contato com o suporte do Notion.

Este projeto implementa um servidor MCP para a API do Notion.

---

⚠️ Mudanças de quebra na versão 2.0.0

A versão 2.0.0 migra para a API do Notion 2025-09-03, que introduz fontes de dados como a abstração principal para bancos de dados.

O que mudou

Ferramentas removidas (3):

• post-database-query - substituída por query-data-source
• update-a-database - substituída por update-a-data-source
• create-a-database - substituída por create-a-data-source

Novas ferramentas (7):

• query-data-source - Consulta uma fonte de dados (banco de dados) com filtros e ordenações
• retrieve-a-data-source - Obtém metadados e esquema de uma fonte de dados
• update-a-data-source - Atualiza propriedades da fonte de dados
• create-a-data-source - Cria uma nova fonte de dados
• list-data-source-templates - Lista modelos disponíveis em uma fonte de dados
• move-page - Move uma página para um local pai diferente
• retrieve-a-database - Obtém metadados do banco de dados, incluindo seus IDs de fonte de dados

Mudanças de parâmetros:

• Todas as operações de banco de dados agora usam data_source_id em vez de database_id
• Os valores de filtro de pesquisa mudaram de ["page", "database"] para ["page", "data_source"]
• A criação de páginas agora suporta pais page_id e database_id (para fontes de dados)

Preciso migrar?

Nenhuma mudança de código é necessária. As ferramentas MCP são descobertas automaticamente quando o servidor inicia. Quando você atualizar para a v2.0.0, os clientes de IA verão automaticamente os novos nomes de ferramentas e parâmetros. As ferramentas antigas de banco de dados não estão mais disponíveis.

Se você tiver nomes de ferramentas codificados ou prompts que referenciam as ferramentas antigas de banco de dados, atualize-os para usar as novas ferramentas de fonte de dados:

Ferramenta Antiga (v1.x)	Nova Ferramenta (v2.0)	Mudança de Parâmetro
post-database-query	query-data-source	database_id → data_source_id
update-a-database	update-a-data-source	database_id → data_source_id
create-a-database	create-a-data-source	Sem mudança (usa parent.page_id)

Nota: retrieve-a-database ainda está disponível e retorna metadados do banco de dados, incluindo a lista de IDs de fonte de dados. Use retrieve-a-data-source para obter o esquema e as propriedades de uma fonte de dados específica.

Total de ferramentas agora: 22 (eram 19 na v1.x)

---

Conteúdo da página como Markdown

O servidor expõe duas ferramentas para trabalhar com conteúdo de página como Markdown aprimorado em vez de JSON de blocos, o que é significativamente mais eficiente em tokens para agentes de IA:

• retrieve-page-markdown — Lê o conteúdo completo de uma página como Markdown (GET /v1/pages/{page_id}/markdown). Passe include_transcript: true para incluir transcrições de notas de reunião.
• update-page-markdown — Edita o conteúdo de uma página com Markdown (PATCH /v1/pages/{page_id}/markdown). Prefira replace_content para sobrescrever a página inteira, ou update_content para edições direcionadas de localizar e substituir.

Esses endpoints exigem a versão 2026-03-11 da API do Notion. O servidor agora obtém o cabeçalho Notion-Version por operação da especificação OpenAPI, então essas ferramentas usam 2026-03-11 enquanto o restante da API continua usando 2025-09-03 — sem necessidade de configuração. Se você definir Notion-Version manualmente via OPENAPI_MCP_HEADERS, seu valor terá precedência para todas as ferramentas.

---

Instalação

1. Configurando a integração no Notion

Vá para 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 (por exemplo, você não poderá excluir bancos de dados via MCP), há um risco não nulo para os dados do workspace ao expô-los a LLMs. Usuários preocupados com segurança podem querer configurar ainda mais as Capabilities da Integração.

Por exemplo, você pode criar um token de integração somente leitura dando apenas acesso de "Read content" na aba "Configuration":

2. Conectando conteúdo à integração

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

Para fazer isso, visite a aba Access nas configurações da sua integração interna. Edite o acesso e selecione as páginas que deseja usar.

Alternativamente, você pode conceder acesso à página individualmente. Você precisará visitar a página de destino, clicar nos 3 pontos e selecionar "Connect to integration".

3. Adicionando a configuração MCP ao seu cliente

Usando npm

Cursor & Claude

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

Opção 1: Usando NOTION_TOKEN (recomendado)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Opção 2: Usando OPENAPI_MCP_HEADERS (para casos de uso avançados)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}

Zed

Adicione o seguinte ao seu settings.json

{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}

GitHub Copilot CLI

Use o Copilot CLI para adicionar interativamente o servidor MCP:

/mcp add

Alternativamente, crie ou edite o arquivo de configuração ~/.copilot/mcp-config.json e adicione:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Para mais informações, veja a documentação do Copilot CLI.

Usando Docker

Há duas opções para executar o servidor MCP com Docker:

Opção 1: Usando a imagem oficial do Docker Hub

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

Usando NOTION_TOKEN (recomendado):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Usando OPENAPI_MCP_HEADERS (para casos de uso avançados):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "mcp/notion"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
      }
    }
  }
}

Esta abordagem:

• Usa a imagem oficial do Docker Hub
• Lida corretamente com o escape JSON via variáveis de ambiente
• Fornece um método de configuração mais confiável

Opção 2: Construindo a imagem Docker localmente

Você também pode construir e executar a imagem Docker localmente. Primeiro, construa a imagem Docker:

docker compose build

Então, adicione o seguinte ao seu .cursor/mcp.json ou claude_desktop_config.json

Usando NOTION_TOKEN (recomendado):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

Usando OPENAPI_MCP_HEADERS (para casos de uso avançados):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}",
        "notion-mcp-server"
      ]
    }
  }
}

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:

Opções de transporte

O servidor Notion MCP suporta dois modos de transporte:

Transporte STDIO (padrão)

O modo de transporte padrão usa entrada/saída padrão para comunicação. Este é o transporte MCP padrão usado pela maioria dos clientes, como o Claude Desktop.

# Run with default stdio transport
npx @notionhq/notion-mcp-server

# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio

Transporte HTTP Streamable

Para aplicativos baseados na web ou clientes que preferem comunicação HTTP, você pode usar o transporte HTTP Streamable:

# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http

# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080

# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0

# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

Ao usar o transporte HTTP Streamable, o servidor estará disponível em http://127.0.0.1:<port>/mcp por padrão.

Autenticação

O transporte HTTP Streamable exige autenticação por token bearer por segurança. Você tem três opções:

Opção 1: Token gerado automaticamente (apenas para desenvolvimento)

npx @notionhq/notion-mcp-server --transport http

O servidor gerará um token aleatório seguro e o escreverá em um arquivo com permissões restritas:

Generated auth token written to: /tmp/.notion-mcp-auth-token-12345

Opção 2: Token personalizado via linha de comando (recomendado para produção)

npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

Opção 3: Token personalizado via variável de ambiente (recomendado para produção)

AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

O argumento de linha de comando --auth-token tem precedência sobre a variável de ambiente AUTH_TOKEN se ambos forem fornecidos.

Opção insegura: desabilitar autenticação HTTP

Você pode desabilitar a autenticação por token bearer apenas com a flag explicitamente insegura:

npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth

AVISO: --unsafe-disable-auth é inseguro. O servidor pode ser alcançável por páginas que você visita via DNS rebinding. Use apenas em uma rede isolada.

Quando a autenticação está desabilitada, o servidor ativa a proteção contra DNS rebinding verificando os cabeçalhos Host e Origin em relação ao host local configurado e aos hosts de loopback. A flag anterior --disable-auth ainda é aceita como um alias obsoleto, mas imprimirá um aviso.

Fazendo requisições HTTP

Todas as requisições ao transporte HTTP Streamable devem incluir o token bearer no cabeçalho Authorization:

# Example request
curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Nota: Certifique-se de definir a variável de ambiente NOTION_TOKEN (recomendado) ou a variável de ambiente OPENAPI_MCP_HEADERS com seu token de integração do Notion ao usar qualquer um dos modos de transporte.

Servindo múltiplas integrações (passagem de token por requisição)

Por padrão, o servidor autentica no Notion com um único token incorporado na inicialização, o que trava uma implantação a uma única integração do Notion. Para permitir que uma única implantação sirva múltiplas integrações, habilite a passagem de token para que cada cliente forneça seu próprio token de integração do Notion por conexão:

# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

Os clientes então enviam seu token do Notion na requisição initialize usando o cabeçalho dedicado Notion-Token:

curl -H "Authorization: Bearer <server-auth-token>" \
     -H "Notion-Token: ntn_****" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Como o token é resolvido para cada conexão, em ordem:

1. O cabeçalho Notion-Token (preferido — inequívoco e funciona junto com a autenticação de gateway Authorization do próprio servidor). Se presente, deve ser um token válido do Notion, caso contrário a requisição é rejeitada com 401.
2. Authorization: Bearer ntn_**** — apenas quando a autenticação bearer do próprio servidor está desligada (--unsafe-disable-auth), para que o cabeçalho fique livre para carregar o token do Notion diretamente.
3. Caso contrário, o token de ambiente da inicialização (NOTION_TOKEN / OPENAPI_MCP_HEADERS), se definido, para que a passagem e uma integração padrão possam coexistir em uma única implantação.

Notas:

• Apenas valores com o prefixo de token do Notion (ntn_, legado secret_) são tratados como tokens do Notion, para que o segredo do gateway do servidor e o token do Notion de um locatário nunca colidam.
• Cada token está vinculado à sua sessão MCP; tokens nunca são registrados (apenas um prefixo editado é emitido).
• Esta é uma configuração deliberada de passagem de token. Sempre implante sobre TLS e prefira manter a autenticação bearer do próprio servidor (--auth-token) habilitada como um gateway na frente do tráfego multi-tenant.

Exemplos

1. Usando a seguinte instrução

Comment "Hello MCP" on page "Getting started"

A IA planejará corretamente duas chamadas de API, v1/search e v1/comments, para realizar a tarefa

1. Da mesma forma, a seguinte instrução resultará em uma nova página chamada "Notion MCP" adicionada à página pai "Development"

Add a page titled "Notion MCP" to page "Development"

1. Você também pode referenciar o ID do conteúdo diretamente

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Desenvolvimento

Build e teste

npm run build
npm test

Execução

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

Testando alterações localmente no Cursor:

1. Execute o comando npm link a partir da raiz do repositório para criar um symlink global na máquina para o pacote notion-mcp-server.
2. Mescle o trecho de configuração abaixo no mcp.json do Cursor (ou outro cliente MCP com o qual você queira testar).
3. (Limpeza) execute npm unlink a partir da raiz do repositório.

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

Publicação

npm login
npm publish --access public