API MCP de Notion

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona funciones avanzadas de gestión de listas de tareas y organización de contenido mediante la API de Notion. MCP permite que los modelos de IA interactúen con herramientas y servicios externos, lo que facilita una integración fluida con las potentes funciones de Notion.

Descripción general de MCP

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

• Gestión de tareas : cree, actualice y realice un seguimiento de tareas con texto enriquecido, fechas de vencimiento, prioridades y subtareas anidadas

• Operaciones de base de datos : cree y administre bases de datos de Notion con propiedades, filtros y vistas personalizados

• Organización del contenido : estructura y formatea el contenido con compatibilidad con Markdown, listas jerárquicas y operaciones en bloque

• Integración en tiempo real : interacción directa con el espacio de trabajo, las páginas y las bases de datos de Notion a través de una implementación asincrónica limpia

Lista completa de funciones →

Related MCP server: Notion MCP Server

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

Empezando

1. Crear una integración de nociones

1. Vaya a https://www.notion.so/my-integrations

2. Haga clic en "Nueva integración"

3. Nombre su integración (por ejemplo, "Mi integración MCP")

4. Seleccione el espacio de trabajo donde utilizará la integración

5. Copia el "Token de integración interna": este será tu NOTION_API_KEY

   • Debería comenzar con "ntn_"

2. Configurar Notion Access

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. Crea una nueva página o abre una existente donde quieras crear bases de datos

3. Haga clic en el menú ••• en la parte superior derecha

4. Seleccione “Agregar conexiones” y elija su integración

5. Copia el ID de la página de 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 de Notion existente

2. Asegúrate de que esté conectado a tu integración (menú ••• > Agregar conexiones)

3. Copiar el ID de la base de datos de 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. Crear entorno virtual:

cd notion-api-mcp
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

2. Instalar dependencias:

uv pip install -e .

3. Configurar el entorno:

cp .env.integration.template .env

4. Edite .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: Si bien el servidor admite archivos .env y variables de entorno, Claude Desktop requiere específicamente una configuración en su archivo de configuración para usar el MCP.

Agregar a la 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 a la configuración de Claude Desktop para que Claude pueda usar el MCP. El archivo .env se utiliza principalmente para desarrollo y pruebas locales.

Documentación

• Detalles de configuración : opciones de configuración detalladas y variables de entorno

• Características : lista completa de funciones y capacidades

• Arquitectura : descripción general de las herramientas disponibles y ejemplos de uso

• Referencia de API : puntos finales de API detallados y detalles de implementación

• Matriz de cobertura de pruebas : cobertura de pruebas y estado de validación

• Dependencias : dependencias del proyecto e información de la versión

• Registro de cambios : progreso del desarrollo y actualizaciones

Desarrollo

El servidor utiliza funciones asincrónicas modernas de Python en todas partes:

• Configuración de tipos seguros utilizando modelos de Pydantic

• HTTP asíncrono que utiliza 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 completo:

• Salida de consola para desarrollo

• Registro de archivos cuando se ejecuta como servicio

• Mensajes de error detallados

• Registro de solicitud/respuesta en el nivel de depuración

Configure PYTHONPATH para incluir la raíz del proyecto cuando se ejecute directamente:

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

Desarrollo futuro

Mejoras planificadas:

1. Optimización del rendimiento

   • Agregar almacenamiento en caché de solicitudes

   • Optimizar las consultas de la base de datos

   • Implementar la agrupación de conexiones

2. Funciones avanzadas

   • Compatibilidad con 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 la API

   • Herramientas CLI para operaciones comunes

   • Ejemplos de código adicionales

   • Monitoreo del rendimiento

4. Mejoras en las pruebas

   • Puntos de referencia de rendimiento

   • Pruebas de carga

   • Casos extremos adicionales

   • Pruebas de integración extendidas