Napkin.AI MCP Server

Servidor MCP para generar infografías dinámicamente usando Napkin.AI

Documentación

Aviso: Este es un servidor MCP no oficial mantenido por la comunidad para Napkin AI. No está afiliado, respaldado ni soportado oficialmente por Napkin AI o Second Layer, Inc. Para productos y soporte oficiales de Napkin AI, visita napkin.ai.

Compatibilidad de API: Probado con Napkin AI API v1.1.16. Las versiones más recientes de la API pueden introducir cambios incompatibles.

Un servidor MCP (Model Context Protocol) para generar infografías y elementos visuales mediante la API de Napkin AI. Este servidor permite que asistentes de IA como Claude generen elementos visuales profesionales a partir de contenido de texto.

Características

Generación de elementos visuales: Genera elementos visuales SVG, PNG o PPT a partir de contenido de texto
Múltiples tipos de visuales: Mapas mentales, diagramas de flujo, líneas de tiempo, comparaciones y más (ver galería)
Manejo asíncrono: Sondeo automático para la generación asíncrona de Napkin AI
Soporte de múltiples almacenamientos: Guarda los elementos visuales generados en:
- Sistema de archivos local
- Amazon S3 (o servicios compatibles con S3)
- Google Drive
- Slack
- Notion
- Telegram
- Discord
Configuración flexible: Variables de entorno o archivo de configuración JSON
Soporte completo de TypeScript: Definiciones de tipos exhaustivas con validación Zod
Reintentos automáticos: Retroceso exponencial para fallos transitorios (429, 5xx)
Registro de depuración: Establece NAPKIN_DEBUG=true para solucionar problemas
Modo de prueba: Valida solicitudes sin llamar a la API
Ayuda de CLI: Ejecuta con --help para obtener información de uso

Requisitos previos

Node.js 18.x o posterior
Una clave de API de Napkin AI (actualmente en vista previa para desarrolladores: contacta con api@napkin.ai)

Inicio rápido

Instalación

npm install -g napkin-ai-mcp

O úsalo directamente con npx:

npx napkin-ai-mcp

Obtén tu clave de API

La API de Napkin AI está actualmente en vista previa para desarrolladores. Para solicitar acceso:

Visita napkin.ai
Contacta con api@napkin.ai para obtener acceso a la API

Guías de integración

Claude Desktop

Añade a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Con almacenamiento local habilitado:

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here",
        "NAPKIN_STORAGE_TYPE": "local",
        "NAPKIN_STORAGE_LOCAL_DIR": "/Users/yourname/napkin-visuals"
      }
    }
  }
}

Después de actualizar la configuración, reinicia Claude Desktop.

Claude Code (CLI)

Añade a la configuración de MCP de Claude Code:

Configuración global: ~/.claude/settings.json Configuración del proyecto: .claude/settings.json

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here",
        "NAPKIN_STORAGE_TYPE": "local",
        "NAPKIN_STORAGE_LOCAL_DIR": "./visuals"
      }
    }
  }
}

O ejecuta el comando de CLI:

claude mcp add napkin-ai -- npx -y napkin-ai-mcp

Luego establece la variable de entorno:

export NAPKIN_API_KEY="your-api-key-here"

Cursor

Añade a la configuración de MCP de Cursor:

Archivo: ~/.cursor/mcp.json

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here",
        "NAPKIN_STORAGE_TYPE": "local",
        "NAPKIN_STORAGE_LOCAL_DIR": "./visuals"
      }
    }
  }
}

Windsurf

Añade a la configuración de MCP de Windsurf:

Archivo: ~/.windsurf/mcp.json

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code con Continue

Añade a la configuración de Continue:

Archivo: ~/.continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "napkin-ai-mcp"],
          "env": {
            "NAPKIN_API_KEY": "your-api-key-here"
          }
        }
      }
    ]
  }
}

Cline (extensión de VS Code)

Añade a la configuración de MCP de Cline en VS Code:

Abre la configuración de VS Code
Busca "Cline MCP"
Añade la configuración del servidor:

{
  "napkin-ai": {
    "command": "npx",
    "args": ["-y", "napkin-ai-mcp"],
    "env": {
      "NAPKIN_API_KEY": "your-api-key-here"
    }
  }
}

Herramientas disponibles

Una vez configurado, tu asistente de IA tendrá acceso a estas herramientas:

Herramienta	Descripción
`generate_visual`	Envía una solicitud de generación visual (asíncrona)
`check_status`	Comprueba el estado de una solicitud de generación
`download_visual`	Descarga un elemento visual generado como base64
`generate_and_wait`	Genera y espera la finalización
`generate_and_save`	Genera y guarda en el almacenamiento configurado
`list_styles`	Obtiene información sobre los estilos disponibles
`verify_api_key`	Verifica que tu clave de API sea válida y funcione

Ejemplos de indicaciones

Una vez configurado, prueba estas indicaciones con tu asistente de IA:

"Crea un mapa mental que visualice los conceptos clave del aprendizaje automático"
"Genera un diagrama de flujo que muestre el proceso de registro de usuarios"
"Haz una línea de tiempo de los principales eventos en la historia de la informática"
"Crea una infografía que compare las API REST vs GraphQL"

Configuración

Variables de entorno

Variable	Descripción	Obligatoria
`NAPKIN_API_KEY`	Clave de API de Napkin AI	Sí
`NAPKIN_API_BASE_URL`	URL base de API personalizada	No
`NAPKIN_STORAGE_TYPE`	Tipo de almacenamiento: `local`, `s3`, `google-drive`, `slack`, `notion`, `telegram`, `discord`	No
`NAPKIN_POLLING_INTERVAL`	Intervalo de sondeo en ms (predeterminado: 2000)	No
`NAPKIN_MAX_WAIT_TIME`	Tiempo máximo de espera en ms (predeterminado: 300000)	No

Configuración de almacenamiento

Almacenamiento local

Guarda los elementos visuales en un directorio local:

NAPKIN_STORAGE_TYPE=local
NAPKIN_STORAGE_LOCAL_DIR=./output

Los archivos se guardan con el formato: napkin-{request_id}-{index}-{color_mode}.{format}

Nota para usuarios de Claude Desktop: Claude Desktop se ejecuta en un entorno de espacio aislado y no puede acceder a rutas del sistema de archivos local. Aunque los archivos se guardan correctamente, Claude Desktop no puede mostrarlos ni abrirlos directamente. Para Claude Desktop, considera usar un proveedor de almacenamiento en la nube (S3, Google Drive, etc.) que devuelva URL accesibles. Claude Code tiene acceso completo al sistema de archivos y funciona sin problemas con el almacenamiento local.

Amazon S3

Guarda los elementos visuales en un bucket de S3 (también funciona con servicios compatibles con S3 como MinIO, DigitalOcean Spaces, Cloudflare R2):

NAPKIN_STORAGE_TYPE=s3
NAPKIN_STORAGE_S3_BUCKET=my-bucket
NAPKIN_STORAGE_S3_REGION=eu-west-1
NAPKIN_STORAGE_S3_PREFIX=napkin-visuals/  # Optional path prefix
NAPKIN_STORAGE_S3_ENDPOINT=https://s3.example.com  # Optional, for S3-compatible services
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

Permisos IAM necesarios:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject"],
      "Resource": "arn:aws:s3:::my-bucket/napkin-visuals/*"
    }
  ]
}

Google Drive

Guarda los elementos visuales en una carpeta de Google Drive mediante una cuenta de servicio:

NAPKIN_STORAGE_TYPE=google-drive
NAPKIN_STORAGE_GDRIVE_FOLDER_ID=1ABC...xyz
NAPKIN_STORAGE_GDRIVE_CREDENTIALS=./service-account.json

Pasos de configuración:

Ve a Google Cloud Console
Crea un proyecto nuevo o selecciona uno existente
Habilita la API de Google Drive
Ve a "IAM y administración" → "Cuentas de servicio" → "Crear cuenta de servicio"
Descarga el archivo de clave JSON y guárdalo como service-account.json
Comparte tu carpeta de destino de Google Drive con el correo de la cuenta de servicio (termina en @*.iam.gserviceaccount.com)
Obtén el ID de la carpeta desde la URL: https://drive.google.com/drive/folders/{FOLDER_ID}

Slack

Sube elementos visuales a un canal de Slack:

NAPKIN_STORAGE_TYPE=slack
NAPKIN_STORAGE_SLACK_CHANNEL=C0123456789
NAPKIN_STORAGE_SLACK_TOKEN=xoxb-your-bot-token

Pasos de configuración:

Ve a Slack API y crea una aplicación nueva
En "OAuth y permisos", añade estos ámbitos de token de bot:
- files:write - Subir archivos
- chat:write - Publicar mensajes (opcional)
Instala la aplicación en tu espacio de trabajo
Copia el "Token de OAuth de usuario de bot" (comienza con xoxb-)
Obtén el ID del canal: haz clic derecho en un canal → "Ver detalles del canal" → desplázate hasta el final

Nota: El bot debe ser invitado al canal con /invite @your-bot-name

Notion

Sube elementos visuales a una página de Notion:

NAPKIN_STORAGE_TYPE=notion
NAPKIN_STORAGE_NOTION_TOKEN=secret_abc123...
NAPKIN_STORAGE_NOTION_PAGE_ID=12345678-abcd-1234-abcd-123456789abc
NAPKIN_STORAGE_NOTION_DATABASE_ID=optional-db-id  # Optional

Pasos de configuración:

Ve a Integraciones de Notion y crea una integración nueva
Copia el "Token de integración interna" (comienza con secret_)
Abre la página de destino en Notion y haz clic en "..." → "Añadir conexiones" → selecciona tu integración
Obtén el ID de la página desde la URL: https://notion.so/Page-Name-{PAGE_ID} (el ID de 32 caracteres al final)

Nota: Notion tiene límites de tamaño de archivo. Para elementos visuales grandes, considera usar S3 o Google Drive.

Envía elementos visuales a un chat o canal de Telegram:

NAPKIN_STORAGE_TYPE=telegram
NAPKIN_STORAGE_TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
NAPKIN_STORAGE_TELEGRAM_CHAT_ID=-1001234567890

Pasos de configuración:

Envía un mensaje a @BotFather en Telegram y crea un bot nuevo con /newbot
Copia el token del bot (formato: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
Añade el bot a tu grupo/canal como administrador (para canales) o miembro (para grupos)
Obtén el ID del chat:
- Para grupos: Añade a @userinfobot al grupo; mostrará el ID del chat
- Para canales: Reenvía un mensaje del canal a @userinfobot
- Para chats privados: Envía un mensaje a tu bot y luego visita https://api.telegram.org/bot<TOKEN>/getUpdates

Nota: Los ID de canal comienzan con -100, los ID de grupo son números negativos y los ID de usuario son positivos.

Discord

Envía elementos visuales a un canal de Discord mediante webhook:

NAPKIN_STORAGE_TYPE=discord
NAPKIN_STORAGE_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/123456789/abcdef...
NAPKIN_STORAGE_DISCORD_USERNAME=Napkin AI  # Optional

Pasos de configuración:

Abre Discord y ve al canal donde deseas recibir los elementos visuales
Haz clic en el icono de engranaje (Editar canal) → Integraciones → Webhooks → Nuevo webhook
Ponle un nombre y, opcionalmente, sube un avatar
Haz clic en "Copiar URL de webhook"

Nota: No se requiere configuración de bot: los webhooks son la forma más sencilla de publicar en Discord.

Configuración visual predeterminada

NAPKIN_DEFAULT_FORMAT=svg       # svg, png, or ppt
NAPKIN_DEFAULT_LANGUAGE=en-GB   # BCP 47 language tag
NAPKIN_DEFAULT_COLOR_MODE=light # light, dark, or both
NAPKIN_DEFAULT_ORIENTATION=auto # auto, horizontal, vertical, or square

Configuración JSON

Crea un archivo config.json:

{
  "napkinApiKey": "your-api-key",
  "storage": {
    "type": "local",
    "directory": "./visuals"
  },
  "defaults": {
    "format": "svg",
    "language": "en-GB",
    "color_mode": "light"
  }
}

Parámetros de las herramientas

generate_visual / generate_and_wait / generate_and_save

Parámetro	Tipo	Descripción
`content`	string	Obligatorio. Contenido de texto a visualizar
`format`	string	Formato de salida: `svg`, `png` o `ppt` (predeterminado: `svg`)
`dry_run`	boolean	Valida la solicitud sin llamar a la API (predeterminado: `false`)
`context`	string	Contexto adicional para la generación (no se muestra en el visual)
`language`	string	Etiqueta de idioma BCP 47 (p. ej., `en-GB`). Predeterminado: `en`
`style_id`	string	Identificador de estilo de Napkin AI. Consulta estilos
`visual_id`	string	Regenera un diseño visual específico con contenido nuevo
`visual_ids`	string[]	Matriz de ID de elementos visuales (la longitud debe coincidir con `number_of_visuals`)
`visual_query`	string	Tipo de visual: `mindmap`, `flowchart`, `timeline`, etc.
`visual_queries`	string[]	Matriz de consultas visuales (la longitud debe coincidir con `number_of_visuals`)
`number_of_visuals`	number	Variaciones a generar (1-4, predeterminado: 1)
`transparent_background`	boolean	Usar fondo transparente (predeterminado: false)
`color_mode`	string	`light`, `dark` o `both` (predeterminado: `light`)
`width`	number	Ancho en píxeles (solo PNG, 100-10000)
`height`	number	Alto en píxeles (solo PNG, 100-10000)
`orientation`	string	`auto`, `horizontal`, `vertical` o `square`
`text_extraction_mode`	string	`auto`, `rewrite` o `preserve` (predeterminado: `auto`)
`sort_strategy`	string	`relevance`, `random` o `variation` (predeterminado: `relevance`)

Nota: visual_id/visual_ids y visual_query/visual_queries son mutuamente excluyentes.

Ejemplo de salida

Aquí tienes algunos ejemplos de elementos visuales generados con este servidor MCP. Cada ejemplo muestra el texto de entrada y el elemento visual resultante.

Mapa mental

Texto de entrada:

# Benefits of Visual Communication

## Speed
- Processed 60,000x faster than text
- Instant pattern recognition

## Retention
- 80% of what we see is remembered
- Only 20% of text is retained

## Engagement
- 94% more views than text-only
- Higher social sharing rates

Parámetros: format: "svg", visual_query: "mindmap", language: "en-GB"

Ver elemento visual generado

Mind Map Example

### Diagrama de flujo

Texto de entrada:

# User Registration Flow

1. User clicks "Sign Up" button
2. Enter email address
3. System validates email format
4. If invalid, show error message
5. If valid, send verification email
6. User clicks verification link
7. Create password
8. Validate password strength
9. If strong, create account
10. Redirect to dashboard

Parámetros: format: "svg", visual_query: "flowchart", language: "en-GB"

Ver visual generado

Flowchart Example

Línea de tiempo

Texto de entrada:

# History of Artificial Intelligence

## 1950
Alan Turing publishes "Computing Machinery and Intelligence"

## 1956
The term "Artificial Intelligence" is coined

## 1997
IBM's Deep Blue defeats world chess champion

## 2016
AlphaGo defeats Go world champion Lee Sedol

## 2022
ChatGPT launches, bringing LLMs to the mainstream

Parámetros: format: "svg", visual_query: "timeline", language: "en-GB"

Ver visual generado

Timeline Example

Consulte más ejemplos en la Galería de Napkin AI.

Tipos de consulta visual

mindmap - Visualizaciones de mapas mentales
flowchart - Flujos de proceso y diagramas
timeline - Eventos cronológicos
comparison - Comparaciones lado a lado
hierarchy - Estructuras organizativas
cycle - Procesos cíclicos
list - Listas con viñetas o numeradas
matrix - Comparaciones basadas en cuadrículas

Uso programático

import { NapkinClient, createNapkinMcpServer } from "napkin-ai-mcp";

// Use the client directly
const client = new NapkinClient({
  apiKey: "your-api-key",
});

const result = await client.generateAndWait({
  format: "svg",
  content: "# My Visual\n\n- Point 1\n- Point 2",
  visual_query: "mindmap",
});

// Download the file using the URL from generated_files
if (result.generated_files && result.generated_files.length > 0) {
  const buffer = await client.downloadFile(result.generated_files[0].url);
  // buffer contains the SVG content
}

Desarrollo

# Clone the repository
git clone https://github.com/LouisChanCLY/napkin-ai-mcp.git
cd napkin-ai-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

Solución de problemas

"NAPKIN_API_KEY es requerida"

Asegúrese de haber establecido la variable de entorno NAPKIN_API_KEY en su configuración de MCP.

"Almacenamiento no configurado"

La herramienta generate_and_save requiere configuración de almacenamiento. Añada una de las configuraciones de almacenamiento anteriores.

La generación de visuales agota el tiempo de espera

Aumente NAPKIN_MAX_WAIT_TIME (predeterminado: 300000 ms = 5 minutos).

Problemas de conexión

Asegúrese de que Node.js 18+ esté instalado
Compruebe que su clave API sea válida
Verifique la conectividad de red a api.napkin.ai

Referencia de API

Sitio web de Napkin AI
Galería de visuales - Vea ejemplos de visuales generados
Documentación de API
Estilos disponibles
Especificación MCP

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lea nuestra Guía de contribución antes de enviar solicitudes de extracción.