🎨 Canva MCP Server

Conecta tus asistentes de IA (Google Antigravity, Gemini CLI, Claude Desktop, Cursor) directamente con tu cuenta de Canva a través de la API oficial (Canva Connect API). Crea, busca, exporta y sube diseños mediante lenguaje natural.

⚡ Inicio Rápido (Quickstart)

1. Configuración Directa vía npx

Puedes ejecutarlo directamente con npx sin necesidad de clonar el repositorio:

🤖 Google Antigravity / Gemini CLI (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "canva": {
      "command": "npx",
      "args": ["-y", "--package", "@elisbanpaco/mcp-canva-gemini-cli", "mcp-canva"],
      "env": {
        "CANVA_CLIENT_ID": "tu_client_id",
        "CANVA_CLIENT_SECRET": "tu_client_secret"
      }
    }
  }
}

🟣 Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "canva": {
      "command": "npx",
      "args": ["-y", "--package", "@elisbanpaco/mcp-canva-gemini-cli", "mcp-canva"],
      "env": {
        "CANVA_CLIENT_ID": "tu_client_id",
        "CANVA_CLIENT_SECRET": "tu_client_secret"
      }
    }
  }
}

💻 Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "canva": {
      "command": "npx",
      "args": ["-y", "--package", "@elisbanpaco/mcp-canva-gemini-cli", "mcp-canva"],
      "env": {
        "CANVA_CLIENT_ID": "tu_client_id",
        "CANVA_CLIENT_SECRET": "tu_client_secret"
      }
    }
  }
}

🧰 Herramientas Disponibles

Una vez conectado, puedes pedirle a tu IA:

| Herramienta | ¿Qué hace? | Ejemplo de Prompt | | :--- | :--- | :--- | | canva_list_designs | Lista tus diseños recientes con miniaturas y enlaces de edición. | "Muéstrame mis presentaciones recientes en Canva" | | canva_get_design | Obtiene los detalles, páginas y URLs de un diseño por su ID. | "Dame la información del diseño con ID DAHKDKZXFcQ" | | canva_create_design | Crea un diseño nuevo (presentación, documento, post de Instagram, etc.). | "Crea un post de Instagram en Canva titulado Lanzamiento 2026" | | canva_export_design | Exporta un diseño a PNG, JPG, PDF o PPTX y te da el link de descarga. | "Exporta mi presentación a formato PDF" | | canva_list_folders | Explora el contenido de tu carpeta raíz de Canva. | "¿Qué elementos tengo en mi carpeta principal de Canva?" | | canva_list_folder_items | Lista los elementos dentro de una carpeta específica. | "Muéstrame los archivos dentro de la carpeta con ID X" | | canva_create_folder | Crea una nueva carpeta en tu Canva. | "Crea una carpeta llamada Proyectos 2026" | | canva_upload_asset | Sube una imagen local de tu computadora a Canva. | "Sube la imagen ./banner.png a mi cuenta de Canva" | | canva_get_auth_status | Verifica el estado de conexión y validez de los tokens. | "Revisa si mi conexión con Canva está activa" |

🔑 Configuración Inicial de Credenciales

1. Entra a Canva Developers y haz clic en Your integrations.

2. Haz clic en Create an integration $\rightarrow$ Elige Public.

   

3. En Credentials, copia tu Client ID y genera tu Client Secret.

4. En Scopes, activa los permisos (son los únicos compatibles):

   • design:content:read, design:content:write, design:meta:read
   • asset:read, asset:write, folder:read, folder:write, app:read

   

5. En Authentication, agrega la URL de redirección exacta: http://127.0.0.1:3000/callback

   

Autenticación (Solo la primera vez)

Como Canva exige credenciales por usuario, abre tu terminal y ejecuta esto para autenticarte y guardar los tokens de forma segura:

# En Linux/macOS
export CANVA_CLIENT_ID="tu_client_id"
export CANVA_CLIENT_SECRET="tu_client_secret"
npx -p @elisbanpaco/mcp-canva-gemini-cli mcp-canva-auth

# En Windows (PowerShell)
$env:CANVA_CLIENT_ID="tu_client_id"
$env:CANVA_CLIENT_SECRET="tu_client_secret"
npx -p @elisbanpaco/mcp-canva-gemini-cli mcp-canva-auth

Se abrirá tu navegador para confirmar. ¡Listo! Tus tokens se guardarán con permisos 0600 en tu sistema operativo.

🏗️ Arquitectura y Seguridad

sequenceDiagram
    autonumber
    actor User as Usuario / Asistente IA
    participant MCP as Canva MCP Server (Stdio)
    participant Vault as Bóveda de Tokens (~/.config/canva-mcp)
    participant CanvaOAuth as Canva OAuth2 (PKCE S256)
    participant CanvaAPI as Canva Connect API (REST v1)

    Note over User,CanvaAPI: 1. Flujo de Autenticación (pnpm auth)
    MCP->>CanvaOAuth: Inicia flujo PKCE con desafío SHA-256
    CanvaOAuth-->>MCP: Redirección con Código de Autorización
    MCP->>CanvaOAuth: Intercambio de código por Tokens de acceso
    CanvaOAuth-->>MCP: Access Token + Refresh Token
    MCP->>Vault: Guarda en almacenamiento seguro (Permisos 0600)

    Note over User,CanvaAPI: 2. Ejecución de Herramientas en Tiempo Real
    User->>MCP: Llama a herramienta (ej. canva_list_designs)
    MCP->>Vault: Carga token válido (Auto-renovación con Mutex)
    MCP->>CanvaAPI: Petición HTTP Bearer con Exponential Backoff
    CanvaAPI-->>MCP: Respuesta JSON con metadatos y URLs
    MCP-->>User: Resultado estructurado

Características de Ingeniería:

• 🔐 Bóveda OS Segura: Los tokens se guardan en el directorio del sistema (~/.config/canva-mcp/ en Linux/Mac o %APPDATA%\canva-mcp en Windows) con permisos POSIX 0600 (solo legibles por tu usuario).
• ⚡ Mutex Anticolisiones: Previene condiciones de carrera cuando el modelo ejecuta múltiples herramientas en paralelo durante la renovación del token.
• 🛡️ Exponential Backoff: Reintentos automáticos con retroceso exponencial ante límites de tasa (HTTP 429) y caídas temporales (5xx).
• 🧪 100% Test Coverage: Suite completa de pruebas unitarias con Vitest.

🧪 Pruebas y Desarrollo

# Ejecutar suite de pruebas unitarias
pnpm test

# Verificación estricta de tipos TypeScript
pnpm typecheck

# Compilar paquete de producción
pnpm build

📄 Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.