Notion API MCP

Interactúa con la API de Notion para gestionar listas de tareas, bases de datos y organización de contenido.

GitHub
28
Prueba este MCPPatrocinado

Documentación

Notion API MCP

Un servidor de Model Context Protocol (MCP) que proporciona capacidades avanzadas de gestión de listas de tareas y organización de contenido a través de la API de Notion. MCP permite que los modelos de IA interactúen con herramientas y servicios externos, facilitando una integración perfecta con las potentes funciones de Notion.

Descripción general de MCP

Servidor MCP basado en Python que permite a los modelos de IA interactuar con la API de Notion, proporcionando:

  • Gestión de tareas: Crear, actualizar y realizar seguimiento de tareas con texto enriquecido, fechas de vencimiento, prioridades y subtareas anidadas
  • Operaciones de bases de datos: Crear y gestionar bases de datos de Notion con propiedades personalizadas, filtros y vistas
  • Organización de contenido: Estructurar y formatear contenido con soporte de Markdown, listas jerárquicas y operaciones de bloques
  • Integración en tiempo real: Interacción directa con el espacio de trabajo, páginas y bases de datos de Notion mediante una implementación asíncrona limpia

Lista completa de funciones →

Inicio rápido

# Clone and setup
git clone https://github.com/yourusername/notion-api-mcp.git
cd notion-api-mcp
uv venv && source .venv/bin/activate

# Install and configure
uv pip install -e .
cp .env.integration.template .env

# Add your Notion credentials to .env:
# NOTION_API_KEY=ntn_your_integration_token_here
# NOTION_PARENT_PAGE_ID=your_page_id_here  # For new databases
# NOTION_DATABASE_ID=your_database_id_here  # For existing databases

# Run the server
python -m notion_api_mcp

Primeros pasos

1. Crear una integración de Notion

  1. Vaya a https://www.notion.so/my-integrations
  2. Haga clic en "New integration"
  3. Asigne un nombre a su integración (por ejemplo, "My MCP Integration")
  4. Seleccione el espacio de trabajo donde utilizará la integración
  5. Copie el "Internal Integration Token" - este será su NOTION_API_KEY
    • Debe comenzar con "ntn_"

2. Configurar el acceso a Notion

Necesitará una página principal (para crear nuevas bases de datos) o un ID de base de datos existente:

Opción A: Página principal para nuevas bases de datos

  1. Abra Notion en su navegador
  2. Cree una nueva página o abra una existente donde desee crear bases de datos
  3. Haga clic en el menú ••• en la esquina superior derecha
  4. Seleccione "Add connections" y elija su integración
  5. Copie el ID de la página desde la URL - es la cadena después de la última barra y antes del signo de interrogación
    • Ejemplo: En https://notion.so/myworkspace/123456abcdef..., el ID es 123456abcdef...
    • Este será su NOTION_PARENT_PAGE_ID

Opción B: Base de datos existente

  1. Abra su base de datos existente de Notion
  2. Asegúrese de que esté conectada a su integración (menú ••• > Add connections)
  3. Copie el ID de la base de datos desde la URL
    • Ejemplo: En https://notion.so/myworkspace/123456abcdef...?v=..., el ID es 123456abcdef...
    • Este será su NOTION_DATABASE_ID

3. Instalar el servidor MCP

  1. Cree el entorno virtual:
cd notion-api-mcp
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Instale las dependencias:
uv pip install -e .
  1. Configure el entorno:
cp .env.integration.template .env
  1. Edite el archivo .env con sus credenciales de Notion:
NOTION_API_KEY=ntn_your_integration_token_here

# Choose one or both of these depending on your needs:
NOTION_PARENT_PAGE_ID=your_page_id_here  # For creating new databases
NOTION_DATABASE_ID=your_database_id_here  # For working with existing databases

4. Configurar Claude Desktop

IMPORTANTE: Aunque el servidor admite tanto archivos .env como variables de entorno, Claude Desktop requiere específicamente la configuración en su archivo de configuración para usar el MCP.

Agregue al archivo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "notion-api": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["-m", "notion_api_mcp"],
      "env": {
        "NOTION_API_KEY": "ntn_your_integration_token_here",
        
        // Choose one or both:
        "NOTION_PARENT_PAGE_ID": "your_page_id_here",
        "NOTION_DATABASE_ID": "your_database_id_here"
      }
    }
  }
}

Nota: Incluso si tiene un archivo .env configurado, debe agregar estas variables de entorno al archivo de configuración de Claude Desktop para que Claude use el MCP. El archivo .env es principalmente para desarrollo y pruebas locales.

Documentación

Desarrollo

El servidor utiliza funciones asíncronas modernas de Python en todo momento:

  • Configuración con seguridad de tipos mediante modelos Pydantic
  • HTTP asíncrono usando httpx para un mejor rendimiento
  • Integración limpia de MCP para exponer las capacidades de Notion
  • Limpieza adecuada de recursos y manejo de errores

Depuración

El servidor incluye un registro integral:

  • Salida en consola para desarrollo
  • Registro en archivos cuando se ejecuta como servicio
  • Mensajes de error detallados
  • Registro de solicitudes/respuestas a nivel de depuración

Establezca PYTHONPATH para incluir la raíz del proyecto al ejecutar directamente:

PYTHONPATH=/path/to/project python -m notion_api_mcp

Desarrollo futuro

Mejoras planificadas:

  1. Optimización del rendimiento

    • Agregar caché de solicitudes
    • Optimizar consultas de bases de datos
    • Implementar agrupación de conexiones

  2. Funciones avanzadas

    • Soporte para múltiples espacios de trabajo
    • Operaciones por lotes
    • Actualizaciones en tiempo real
    • Capacidades de búsqueda avanzada

  3. Experiencia del desarrollador

    • Documentación interactiva de API
    • Herramientas CLI para operaciones comunes
    • Ejemplos de código adicionales
    • Monitoreo del rendimiento

  4. Mejoras de pruebas

    • Benchmarks de rendimiento
    • Pruebas de carga
    • Casos límite adicionales
    • Pruebas de integración extendidas