Notion MCP

Servidor MCP do Notion

[!NOTE]

Apresentamos o Notion MCP, um servidor MCP remoto com as seguintes melhorias:

• Instalação fácil via OAuth padrão. Não precisa mais lidar com JSON ou tokens de API.
• Ferramentas poderosas adaptadas para agentes de IA, incluindo edição de páginas em Markdown. Essas ferramentas foram projetadas pensando no consumo otimizado de tokens.

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

Estamos priorizando e fornecendo suporte ativo apenas para o Notion MCP (remoto). Como resultado:

• Podemos descontinuar este repositório do servidor MCP local no futuro.
• Issues e pull requests aqui não são monitorados ativamente.
• Por favor, não registre 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 significativas 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 - Consultar uma fonte de dados (banco de dados) com filtros e ordenações
• retrieve-a-data-source - Obter metadados e esquema de uma fonte de dados
• update-a-data-source - Atualizar propriedades da fonte de dados
• create-a-data-source - Criar uma nova fonte de dados
• list-data-source-templates - Listar modelos disponíveis em uma fonte de dados
• move-page - Mover uma página para um local pai diferente
• retrieve-a-database - Obter 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ágina agora suporta pais tanto page_id quanto database_id (para fontes de dados)

Preciso migrar?

Nenhuma alteração de código necessária. As ferramentas MCP são descobertas automaticamente quando o servidor inicia. Ao 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 façam referência às 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 alteração (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 bloco, o que é significativamente mais eficiente em tokens para agentes de IA:

• retrieve-page-markdown — Ler o conteúdo completo de uma página como Markdown (GET /v1/pages/{page_id}/markdown). Passe include_transcript: true para incorporar transcrições de notas de reunião.
• update-page-markdown — Editar 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 da API do Notion 2026-03-11. 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 — nenhuma configuração necessária. Se você definir Notion-Version por conta própria via OPENAPI_MCP_HEADERS, seu valor terá precedência para todas as ferramentas.

---

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 (por exemplo, você não poderá excluir bancos de dados via MCP), há um risco diferente de zero para os dados do workspace 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 concedendo apenas acesso "Ler conteúdo" na aba "Configuração":

2. Conectando conteúdo à integração

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

Para fazer isso, visite a aba Acesso 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 "Conectar à integração".

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, consulte a documentação do Copilot CLI.

Usando Docker

Existem 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 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

Em seguida, 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 MCP do Notion 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 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 aplicações baseadas 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 requer autenticação de 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 gravará 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 de token bearer apenas com o sinalizador inseguro explícito:

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

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

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

Fazendo requisições HTTP

Todas as requisições para o 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 modo 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 vincula 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_**** — somente quando a autenticação bearer do próprio servidor está desligada (--unsafe-disable-auth), para que o cabeçalho fique livre para transportar o token do Notion diretamente.
3. Caso contrário, o token de ambiente de inicialização (NOTION_TOKEN / OPENAPI_MCP_HEADERS), se definido, para que a passagem e uma integração padrão possam coexistir em uma implantação.

Notas:

• Apenas valores com um 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 inquilino nunca colidam.
• Cada token é vinculado à sua sessão MCP; tokens nunca são registrados (apenas um prefixo censurado é 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-inquilino.

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

Construir e testar

npm run build
npm test

Executar

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 da raiz do repositório para criar um link simbólico global da 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 deseja testar).
3. (Limpeza) execute npm unlink da raiz do repositório.

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

Publicar

npm login
npm publish --access public