notion-mcp-server

OMNIAGH/notion-mcp-server

3.2

If you are the rightful owner of notion-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Notion MCP Server is a comprehensive server for the Notion API, providing full read and write access to Notion databases and pages.

Tools
5
Resources
0
Prompts
0

Notion MCP Server

Un servidor MCP completo para la API de Notion que proporciona acceso integral de lectura y escritura a bases de datos y páginas de Notion.

🚀 Características

Funciones de Lectura

  • list_databases: Lista todas las bases de datos accesibles
  • get_database: Obtiene información detallada de una base de datos específica
  • get_page: Obtiene información detallada de una página específica
  • search_pages: Busca páginas en el espacio de trabajo
  • search_databases: Busca bases de datos en el espacio de trabajo
  • get_block_children: Obtiene bloques hijos de un bloque padre

Funciones de Escritura

  • create_page: Crea una nueva página en Notion
  • create_database: Crea una nueva base de datos en una página padre
  • create_database_with_properties: Crea una base de datos con propiedades predefinidas
  • update_page: Actualiza propiedades de una página
  • append_block_children: Agrega bloques hijos a un bloque padre

Gestión de Credenciales

  • Configuración automática de NOTION_TOKEN en variables de entorno
  • Validación de credenciales y conectividad
  • Autenticación segura con la API de Notion

Manejo de Errores

  • Captura y manejo de errores de API
  • Validación de parámetros con Pydantic
  • Logging detallado para debugging
  • Manejo de rate limits automático

Estructura de Respuesta

  • Respuestas en formato JSON estructurado
  • Conversión automática a formato legible
  • Paginación para grandes conjuntos de datos
  • Manejo de rate limits y reintentos

📋 Requisitos

  • Python 3.10 o superior
  • uv (gestor de paquetes moderno)
  • Token de integración de Notion

🛠️ Instalación

1. Obtener Token de Notion

  1. Ve a https://www.notion.so/my-integrations
  2. Crea una nueva integración interna
  3. Copia el token de integración
  4. Comparte tus páginas y bases de datos con la integración

2. Configurar Variables de Entorno

export NOTION_TOKEN="tu_token_de_integracion_aqui"

3. Instalar Dependencias

# Instalar uv si no lo tienes
curl -LsSf https://astral.sh/uv/install.sh | sh

# Navegar al directorio del proyecto
cd notion-mcp-server

# Las dependencias se instalarán automáticamente al ejecutar run.sh

🚀 Uso

Uso Básico

# Ejecutar el servidor MCP
./run.sh

Ejemplos de Herramientas

Listar Bases de Datos
# Lista todas las bases de datos accesibles
result = await mcp_client.call_tool("list_databases", {
    "page_size": 10
})
Buscar Páginas
# Buscar páginas que contengan "proyecto"
result = await mcp_client.call_tool("search_pages", {
    "query": "proyecto",
    "page_size": 20
})
Crear Página
# Crear una nueva página
result = await mcp_client.call_tool("create_page", {
    "parent_type": "page_id",
    "parent_id": "id_de_la_pagina_padre",
    "title": "Nueva Página",
    "properties": {
        "status": {
            "select": {"name": "En progreso"}
        }
    }
})
Crear Base de Datos
# Crear una nueva base de datos
properties = {
    "Nombre": {
        "title": {}
    },
    "Estado": {
        "select": {
            "options": [
                {"name": "Por hacer", "color": "red"},
                {"name": "En progreso", "color": "yellow"},
                {"name": "Completado", "color": "green"}
            ]
        }
    }
}

result = await mcp_client.call_tool("create_database", {
    "parent_page_id": "id_de_la_pagina_padre",
    "title": "Mi Base de Datos",
    "properties": properties
})

📖 Documentación de Herramientas

Funciones de Lectura

list_databases

Lista todas las bases de datos accesibles por la integración.

Parámetros:

  • start_cursor (opcional): Cursor para paginación
  • page_size (opcional): Número de elementos por página (1-100, por defecto 100)

Retorna: JSON con lista de bases de datos e información de paginación

get_database

Obtiene información detallada de una base de datos específica.

Parámetros:

  • database_id (requerido): ID de la base de datos a obtener

Retorna: JSON con detalles de la base de datos

get_page

Obtiene información detallada de una página específica.

Parámetros:

  • page_id (requerido): ID de la página a obtener

Retorna: JSON con detalles de la página

search_pages

Busca páginas en el espacio de trabajo.

Parámetros:

  • query (opcional): Consulta de búsqueda para filtrar páginas
  • page_size (opcional): Número de resultados a devolver (1-100, por defecto 100)
  • start_cursor (opcional): Cursor para paginación

Retorna: JSON con resultados de búsqueda

search_databases

Busca bases de datos en el espacio de trabajo.

Parámetros:

  • query (opcional): Consulta de búsqueda para filtrar bases de datos
  • page_size (opcional): Número de resultados a devolver (1-100, por defecto 100)
  • start_cursor (opcional): Cursor para paginación

Retorna: JSON con resultados de búsqueda

get_block_children

Obtiene bloques hijos de un bloque padre.

Parámetros:

  • block_id (requerido): ID del bloque padre
  • start_cursor (opcional): Cursor para paginación
  • page_size (opcional): Número de resultados a devolver (1-100, por defecto 100)

Retorna: JSON con bloques hijos

Funciones de Escritura

create_page

Crea una nueva página en Notion.

Parámetros:

  • parent_type (requerido): Tipo de padre ('page_id' o 'database_id')
  • parent_id (requerido): ID del padre (página o base de datos)
  • title (requerido): Título de la nueva página
  • properties (opcional): Propiedades adicionales de la página

Retorna: JSON con información de la página creada

create_database

Crea una nueva base de datos en una página padre.

Parámetros:

  • parent_page_id (requerido): ID de la página padre donde se creará la base de datos
  • title (requerido): Título de la nueva base de datos
  • properties (requerido): Configuración de propiedades de la base de datos

Retorna: JSON con información de la base de datos creada

create_database_with_properties

Crea una base de datos con propiedades predefinidas.

Parámetros:

  • parent_page_id (requerido): ID de la página padre donde se creará la base de datos
  • title (requerido): Título de la nueva base de datos
  • properties (requerido): Configuración de propiedades de la base de datos

Retorna: JSON con información de la base de datos creada

update_page

Actualiza propiedades de una página.

Parámetros:

  • page_id (requerido): ID de la página a actualizar
  • properties (requerido): Propiedades de la página a actualizar

Retorna: JSON con información de la página actualizada

append_block_children

Agrega bloques hijos a un bloque padre.

Parámetros:

  • block_id (requerido): ID del bloque padre
  • children (requerido): Lista de bloques hijos a agregar

Retorna: JSON con información del resultado

Herramientas de Utilidad

validate_credentials

Valida las credenciales de la API de Notion y la conectividad.

Parámetros: Ninguno

Retorna: JSON con estado de validación

🔧 Configuración Avanzada

Variables de Entorno

  • NOTION_TOKEN: Token de integración de Notion (requerido)

Rate Limiting

El servidor maneja automáticamente los límites de tasa de la API de Notion:

  • Retraso configurable entre solicitudes
  • Reintentos automáticos en caso de rate limiting
  • Logging detallado de operaciones

Configuración de MCP

El archivo mcp-server.json contiene la configuración del servidor MCP:

{
  "name": "agent_generated_notion_mcp_server",
  "exhibit_name": "Notion MCP Server",
  "type": 3,
  "command": "sh /ruta/a/notion-mcp-server/run.sh",
  "description": "Servidor MCP completo para la API de Notion..."
}

🧪 Testing

Ejecutar Pruebas

# Instalar dependencias de desarrollo
uv sync --dev

# Ejecutar pruebas
pytest

# Ejecutar pruebas con cobertura
pytest --cov=src tests/

Ejemplos de Uso

# Ejecutar ejemplos
python examples/usage_examples.py

📝 Ejemplos de Casos de Uso

1. Gestión de Proyectos

# Crear base de datos de proyectos
await mcp_client.call_tool("create_database", {
    "parent_page_id": "id_espacio_trabajo",
    "title": "Proyectos",
    "properties": {
        "Nombre": {"title": {}},
        "Estado": {
            "select": {
                "options": [
                    {"name": "Planificación", "color": "blue"},
                    {"name": "Desarrollo", "color": "yellow"},
                    {"name": "Completado", "color": "green"}
                ]
            }
        },
        "Fecha Límite": {"date": {}},
        "Asignado a": {"people": {}}
    }
})

2. Automatización de Contenido

# Buscar y actualizar páginas
pages = await mcp_client.call_tool("search_pages", {"query": "tarea pendiente"})
for page in pages["pages"]:
    await mcp_client.call_tool("update_page", {
        "page_id": page["id"],
        "properties": {
            "Estado": {
                "select": {"name": "En progreso"}
            }
        }
    })

3. Reportes y Análisis

# Obtener todas las bases de datos
databases = await mcp_client.call_tool("list_databases", {"page_size": 100})

# Analizar estructura de cada base de datos
for db in databases["databases"]:
    details = await mcp_client.call_tool("get_database", {
        "database_id": db["id"]
    })
    print(f"Base de datos: {db['title']}")
    print(f"Propiedades: {list(details['database']['properties'].keys())}")

🐛 Solución de Problemas

Error: NOTION_TOKEN no configurado

export NOTION_TOKEN="tu_token_aqui"

Error: Permisos insuficientes

  1. Verifica que la integración tenga acceso a las páginas/bases de datos
  2. En Notion, ve a la página y haz clic en "Compartir"
  3. Agrega tu integración a la lista de acceso

Error: Rate limit

El servidor maneja automáticamente los rate limits, pero si hay muchos errores:

  1. Reduce la frecuencia de las solicitudes
  2. Aumenta el delay entre solicitudes en el código

Error: ID inválido

  1. Verifica que estés usando el ID correcto (formato UUID)
  2. Asegúrate de que el recurso existe y tienes acceso

📚 Referencias

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

  1. Fork el repositorio
  2. Crea una rama para tu feature
  3. Commit tus cambios
  4. Push a la rama
  5. Abre un Pull Request

📄 Licencia

MIT License - Ver archivo LICENSE para más detalles.

👤 Autor

Desarrollado por MiniMax Agent

¡Listo para usar inmediatamente después del deploy! 🚀