Playground / Experimento

Claude Code + Notion MCP

Configurar Claude Code para leer y escribir en un workspace de Notion directamente desde el chat de VS Code, usando el servidor MCP oficial. No es el mismo experimento que Notion como CMS — ese conecta la web a Notion; este conecta el agente de IA a Notion.

Diferencia clave

Notion CMS /now — La web (Next.js) lee la API de Notion para mostrar contenido en producción. Auth vía NOTION_TOKEN en variables de entorno del servidor.

Notion MCP (este experimento) — Claude Code (el agente) lee y escribe en Notion desde el chat. Auth vía token en .mcp.json en la raíz del repo.

Configuración

Un único archivo en la raíz del repo: .mcp.json

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer TU_TOKEN\", \"Notion-Version\": \"2022-06-28\"}"
      }
    }
  }
}

El token se genera en notion.so/profile/integrations → New integration → Internal Integration Secret (ntn_...).

Prerequisitos

  • Crear una integration interna en Notion: notion.so/profile/integrations → New integration → Internal Integration Secret
  • Compartir las páginas relevantes con esa integration — ··· → Connect to → tu integration. Las páginas no conectadas no son accesibles aunque el token sea válido.
  • Reiniciar Claude Code tras cambiar el token. El MCP server se carga al arrancar — un cambio en .mcp.json no se aplica en caliente.
  • El token nunca va a git. Añadir .mcp.json a .gitignore o usar variables de entorno del sistema.

Error 401 — parte del experimento

Durante la configuración inicial, todas las llamadas a la API de Notion respondían con API token is invalid. Tres causas posibles:

  • El token caducó o fue revocado → regenerar en notion.so/profile/integrations → tu integration → Internal Integration Secret → Regenerate.
  • La página no está conectada a la integration → aunque el token sea válido, Notion solo da acceso a páginas conectadas explícitamente con ··· → Connect to → tu integration.
  • Claude Code no ha sido reiniciado → el MCP server se inicia al arrancar; sustituir el token en .mcp.json no aplica el cambio hasta el siguiente arranque.

Mientras el MCP del proyecto daba 401, Claude Code usó el MCP de Notion de Claude.ai para seguir trabajando — y con él actualizó esta misma página de Notion y construyó este experimento. El error quedó documentado in situ.

Casos de uso

  • Consultar el estado del proyecto y el plan de trabajo sin salir de VS Code
  • Documentar decisiones técnicas directamente en Notion desde el chat
  • Leer notas de diseño para dar contexto a Claude antes de implementar
  • Potencial: automatizar actualizaciones de documentación al hacer commits
Ver el experimento de Notion como CMS →