Cómo conectar Claude con Notion paso a paso

Antes de tocar código necesitas credenciales de Notion. Ve a notion.so/my-integrations y pulsa 'New integration'. Dale un nombre (por ejemplo 'Claude Connector'), asócialo a tu workspace y elige el tipo 'Internal'. En la sección de capacidades marca al menos 'Read content', 'Insert content' y 'Update content' según lo que quieras que Claude pueda hacer. Al guardar, Notion genera un 'Internal Integration Secret' que empieza por 'ntn_' o 'secret_'. Cópialo: es tu NOTION_TOKEN. Este paso es puramente de configuración pero es donde falla más gente en España y LATAM, porque crean la integración y olvidan el paso crítico del paso 2: compartir páginas concretas con ella. Una integración recién creada no ve absolutamente nada de tu workspace hasta que le concedes acceso explícito a páginas o bases de datos.

# Guarda tus credenciales como variables de entorno
export NOTION_TOKEN="ntn_tu_token_aqui"
export ANTHROPIC_API_KEY="sk-ant-tu_api_key"

Este es el paso que rompe la mayoría de integraciones. En Notion, abre la página o base de datos que quieres exponer a Claude. Pulsa el menú de tres puntos (arriba a la derecha) o el botón de compartir, busca 'Connections' o 'Conexiones', y selecciona la integración que creaste. A partir de ese momento la integración —y por tanto Claude— puede leer y modificar esa página y todas sus subpáginas. Si trabajas con una base de datos, comparte la base de datos entera, no solo una fila. Anota el ID de la página o base de datos: está en la URL, es la cadena de 32 caracteres hexadecimales tras el nombre y antes del '?'. Por ejemplo, en notion.so/miespacio/Proyectos-1a2b3c4d... el ID es '1a2b3c4d...'. Lo necesitarás para las llamadas a la API.

# La URL de Notion tiene esta forma:
# https://www.notion.so/workspace/Nombre-1a2b3c4d5e6f7890abcdef1234567890
# El database_id / page_id son esos 32 caracteres hex finales

La forma más directa y sin escribir apenas código es usar el Model Context Protocol (MCP), el estándar de Anthropic para conectar Claude con herramientas externas. Notion publica un servidor MCP oficial que corre con npx. Abre el archivo de configuración de Claude Desktop: en macOS está en ~/Library/Application Support/Claude/claude_desktop_config.json y en Windows en %APPDATA%\Claude\claude_desktop_config.json. Añade el servidor de Notion pasándole tu token vía la cabecera de autorización. Guarda y reinicia Claude Desktop por completo. Verás un icono de herramientas en la caja de chat; al pulsarlo aparecerán las acciones de Notion disponibles. Ahora puedes pedirle a Claude en lenguaje natural 'busca mis notas de la reunión de ayer' o 'crea una página con este resumen', y ejecutará las llamadas a Notion por ti.

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

Si prefieres control programático —por ejemplo para un backend o un agente propio— puedes combinar la API de Notion con la API de Claude directamente. Primero recuperas contenido de Notion con su REST API, luego se lo pasas a Claude como contexto. Este patrón es la base de cualquier integración a medida: Notion es la fuente de datos y Claude el motor de razonamiento. El siguiente script en Python consulta una base de datos, extrae los títulos de las páginas y pide a claude-opus-4-8 que genere un resumen. Instala primero las dependencias con 'pip install anthropic requests'.

import os, requests, anthropic

NOTION_TOKEN = os.environ["NOTION_TOKEN"]
DATABASE_ID = "1a2b3c4d5e6f7890abcdef1234567890"

headers = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Notion-Version": "2022-06-28",
    "Content-Type": "application/json",
}

resp = requests.post(
    f"https://api.notion.com/v1/databases/{DATABASE_ID}/query",
    headers=headers, json={"page_size": 20},
)
resp.raise_for_status()

titulos = []
for page in resp.json()["results"]:
    for prop in page["properties"].values():
        if prop["type"] == "title" and prop["title"]:
            titulos.append(prop["title"][0]["plain_text"])

client = anthropic.Anthropic()
msg = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=500,
    messages=[{"role": "user",
        "content": f"Resume estos elementos de mi Notion:\n" + "\n".join(titulos)}],
)
print(msg.content[0].text)

El flujo inverso —que Claude escriba en Notion— cierra el círculo y es lo que convierte la integración en algo realmente útil: generas contenido con IA y lo persistes automáticamente. Para crear una página necesitas el ID de la página o base de datos padre y construir el cuerpo con las propiedades y bloques. El siguiente ejemplo pide a Claude que redacte un resumen y luego lo inserta como una nueva página dentro de tu base de datos. Fíjate en que el título va en 'properties' y el contenido del cuerpo en 'children' como bloques de tipo paragraph. Este patrón se extiende a checklists, encabezados o tablas cambiando el tipo de bloque.

contenido = msg.content[0].text

nueva_pagina = {
    "parent": {"database_id": DATABASE_ID},
    "properties": {
        "Name": {"title": [{"text": {"content": "Resumen generado por Claude"}}]}
    },
    "children": [
        {"object": "block", "type": "paragraph",
         "paragraph": {"rich_text": [{"type": "text",
            "text": {"content": contenido[:1900]}}]}}
    ],
}

crear = requests.post("https://api.notion.com/v1/pages",
                      headers=headers, json=nueva_pagina)
crear.raise_for_status()
print("Página creada:", crear.json()["url"])

Antes de dar por buena la integración, valida los dos extremos. Para la ruta MCP, escribe en Claude Desktop 'lista mis páginas de Notion accesibles' y confirma que devuelve resultados reales. Para la ruta API, ejecuta un endpoint de prueba que use el token de Notion. Los tres fallos más habituales tienen diagnóstico claro: un 401 significa token inválido o mal formado en la cabecera; 'object_not_found' significa que la página no está compartida con la integración (vuelve al paso 2); y 'validation_error' suele ser un nombre de propiedad mal escrito o un tipo de bloque incorrecto. Registra siempre el cuerpo completo del error de Notion, porque incluye un mensaje descriptivo en el campo 'message' que dice exactamente qué falló.

# Verifica el token de Notion con una llamada simple
resp = requests.post("https://api.notion.com/v1/search",
                     headers=headers, json={"page_size": 5})
if resp.status_code == 200:
    print("OK, integración activa:", len(resp.json()["results"]), "resultados")
else:
    print("Error", resp.status_code, resp.json().get("message"))