Napkin.AI MCP Server

Servidor MCP para gerar infográficos dinamicamente usando Napkin.AI

Documentação

Aviso: Este é um servidor MCP não oficial, mantido pela comunidade, para o Napkin AI. Não é afiliado, endossado ou oficialmente suportado pelo Napkin AI ou pela Second Layer, Inc. Para produtos e suporte oficiais do Napkin AI, visite napkin.ai.

Compatibilidade com a API: Testado com a API do Napkin AI v1.1.16. Versões mais recentes da API podem introduzir mudanças que quebram a compatibilidade.

Um servidor MCP (Model Context Protocol) para gerar infográficos e visuais usando a API do Napkin AI. Este servidor permite que assistentes de IA, como o Claude, gerem visuais profissionais a partir de conteúdo de texto.

Recursos

Geração Visual: Gere visuais em SVG, PNG ou PPT a partir de conteúdo de texto
Múltiplos Tipos Visuais: Mapas mentais, fluxogramas, linhas do tempo, comparações e mais (veja a galeria)
Manuseio Assíncrono: Polling automático para a geração assíncrona do Napkin AI
Suporte a Múltiplos Armazenamentos: Salve os visuais gerados em:
- Sistema de arquivos local
- Amazon S3 (ou serviços compatíveis com S3)
- Google Drive
- Slack
- Notion
- Telegram
- Discord
Configuração Flexível: Variáveis de ambiente ou arquivo de configuração JSON
Suporte Completo a TypeScript: Definições de tipos abrangentes com validação Zod
Tentativas Automáticas: Backoff exponencial para falhas transitórias (429, 5xx)
Registro de Depuração: Defina NAPKIN_DEBUG=true para solução de problemas
Modo de Simulação (Dry-Run): Valide solicitações sem chamar a API
Ajuda via CLI: Execute com --help para informações de uso

Pré-requisitos

Node.js 18.x ou posterior
Uma chave de API do Napkin AI (atualmente em pré-visualização para desenvolvedores - entre em contato com api@napkin.ai)

Início Rápido

Instalação

npm install -g napkin-ai-mcp

Ou use diretamente com npx:

npx napkin-ai-mcp

Obtenha Sua Chave de API

A API do Napkin AI está atualmente em pré-visualização para desenvolvedores. Para solicitar acesso:

Visite napkin.ai
Entre em contato com api@napkin.ai para acesso à API

Guias de Integração

Claude Desktop

Adicione ao arquivo de configuração do seu 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"
      }
    }
  }
}

Com armazenamento 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"
      }
    }
  }
}

Após atualizar a configuração, reinicie o Claude Desktop.

Claude Code (CLI)

Adicione às configurações MCP do seu Claude Code:

Configuração global: ~/.claude/settings.json Configuração do projeto: .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"
      }
    }
  }
}

Ou execute o comando CLI:

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

Em seguida, defina a variável de ambiente:

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

Cursor

Adicione à configuração MCP do seu Cursor:

Arquivo: ~/.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

Adicione à configuração MCP do seu Windsurf:

Arquivo: ~/.windsurf/mcp.json

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

VS Code com Continue

Adicione à sua configuração do Continue:

Arquivo: ~/.continue/config.json

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

Cline (Extensão do VS Code)

Adicione às configurações MCP do seu Cline no VS Code:

Abra as configurações do VS Code
Pesquise por "Cline MCP"
Adicione a configuração do servidor:

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

Ferramentas Disponíveis

Após a configuração, seu assistente de IA terá acesso a estas ferramentas:

Ferramenta	Descrição
`generate_visual`	Enviar uma solicitação de geração visual (assíncrona)
`check_status`	Verificar o status de uma solicitação de geração
`download_visual`	Baixar um visual gerado como base64
`generate_and_wait`	Gerar e aguardar a conclusão
`generate_and_save`	Gerar e salvar no armazenamento configurado
`list_styles`	Obter informações sobre estilos disponíveis
`verify_api_key`	Verificar se sua chave de API é válida e está funcionando

Exemplos de Prompts

Após a configuração, experimente estes prompts com seu assistente de IA:

"Crie um mapa mental visualizando os conceitos-chave de aprendizado de máquina"
"Gere um fluxograma mostrando o processo de registro de usuário"
"Faça uma linha do tempo dos principais eventos na história da computação"
"Crie um infográfico comparando APIs REST vs GraphQL"

Configuração

Variáveis de Ambiente

Variável	Descrição	Obrigatório
`NAPKIN_API_KEY`	Chave da API do Napkin AI	Sim
`NAPKIN_API_BASE_URL`	URL base da API personalizada	Não
`NAPKIN_STORAGE_TYPE`	Tipo de armazenamento: `local`, `s3`, `google-drive`, `slack`, `notion`, `telegram`, `discord`	Não
`NAPKIN_POLLING_INTERVAL`	Intervalo de polling em ms (padrão: 2000)	Não
`NAPKIN_MAX_WAIT_TIME`	Tempo máximo de espera em ms (padrão: 300000)	Não

Configuração de Armazenamento

Armazenamento Local

Salve os visuais em um diretório local:

NAPKIN_STORAGE_TYPE=local
NAPKIN_STORAGE_LOCAL_DIR=./output

Os arquivos são salvos com o formato: napkin-{request_id}-{index}-{color_mode}.{format}

Nota para usuários do Claude Desktop: O Claude Desktop é executado em um ambiente sandbox e não pode acessar caminhos do sistema de arquivos local. Embora os arquivos sejam salvos com sucesso, o Claude Desktop não pode exibi-los ou abri-los diretamente. Para o Claude Desktop, considere usar um provedor de armazenamento em nuvem (S3, Google Drive, etc.) que retorna URLs acessíveis. O Claude Code tem acesso total ao sistema de arquivos e funciona perfeitamente com armazenamento local.

Amazon S3

Salve os visuais em um bucket S3 (também funciona com serviços compatíveis com 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

Permissões IAM necessárias:

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

Google Drive

Salve os visuais em uma pasta do Google Drive usando uma conta de serviço:

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

Etapas de configuração:

Acesse o Google Cloud Console
Crie um novo projeto ou selecione um existente
Ative a API do Google Drive
Vá para "IAM & Admin" → "Service Accounts" → "Create Service Account"
Baixe o arquivo de chave JSON e salve como service-account.json
Compartilhe sua pasta de destino do Google Drive com o e-mail da conta de serviço (termina com @*.iam.gserviceaccount.com)
Obtenha o ID da pasta a partir da URL: https://drive.google.com/drive/folders/{FOLDER_ID}

Slack

Envie os visuais para um canal do Slack:

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

Etapas de configuração:

Acesse a Slack API e crie um novo aplicativo
Em "OAuth & Permissions", adicione estes escopos de Token do Bot:
- files:write - Enviar arquivos
- chat:write - Publicar mensagens (opcional)
Instale o aplicativo no seu espaço de trabalho
Copie o "Bot User OAuth Token" (começa com xoxb-)
Obtenha o ID do canal: clique com o botão direito no canal → "View channel details" → role até o final

Nota: O bot deve ser convidado para o canal com /invite @your-bot-name

Notion

Envie os visuais para uma página do 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

Etapas de configuração:

Acesse as Integrações do Notion e crie uma nova integração
Copie o "Internal Integration Token" (começa com secret_)
Abra a página de destino do Notion e clique em "..." → "Add connections" → selecione sua integração
Obtenha o ID da página a partir da URL: https://notion.so/Page-Name-{PAGE_ID} (o ID de 32 caracteres no final)

Nota: O Notion tem limites de tamanho de arquivo. Para visuais grandes, considere usar S3 ou Google Drive.

Envie os visuais para um chat ou canal do Telegram:

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

Etapas de configuração:

Envie uma mensagem para o @BotFather no Telegram e crie um novo bot com /newbot
Copie o token do bot (formato: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
Adicione o bot ao seu grupo/canal como administrador (para canais) ou membro (para grupos)
Obtenha o ID do chat:
- Para grupos: Adicione o @userinfobot ao grupo; ele mostrará o ID do chat
- Para canais: Encaminhe uma mensagem do canal para o @userinfobot
- Para chats privados: Envie uma mensagem para o seu bot e depois visite https://api.telegram.org/bot<TOKEN>/getUpdates

Nota: IDs de canais começam com -100, IDs de grupos são números negativos, IDs de usuários são positivos.

Discord

Envie visuais para um canal do Discord via webhook:

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

Etapas de configuração:

Abra o Discord e vá para o canal onde deseja receber os visuais
Clique no ícone de engrenagem (Editar Canal) → Integrações → Webhooks → Novo Webhook
Dê um nome e, opcionalmente, envie um avatar
Clique em "Copiar URL do Webhook"

Nota: Não é necessário configurar um bot - webhooks são a maneira mais simples de publicar no Discord.

Configurações Visuais Padrão

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

Configuração JSON

Crie um arquivo config.json:

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

Parâmetros das Ferramentas

generate_visual / generate_and_wait / generate_and_save

Parâmetro	Tipo	Descrição
`content`	string	Obrigatório. Conteúdo de texto a ser visualizado
`format`	string	Formato de saída: `svg`, `png` ou `ppt` (padrão: `svg`)
`dry_run`	boolean	Validar a solicitação sem chamar a API (padrão: `false`)
`context`	string	Contexto adicional para a geração (não exibido no visual)
`language`	string	Tag de idioma BCP 47 (por exemplo, `en-GB`). Padrão: `en`
`style_id`	string	Identificador de estilo do Napkin AI. Veja estilos
`visual_id`	string	Regenerar um layout visual específico com novo conteúdo
`visual_ids`	string[]	Matriz de IDs visuais (o comprimento deve corresponder a `number_of_visuals`)
`visual_query`	string	Tipo visual: `mindmap`, `flowchart`, `timeline`, etc.
`visual_queries`	string[]	Matriz de consultas visuais (o comprimento deve corresponder a `number_of_visuals`)
`number_of_visuals`	number	Variações a serem geradas (1-4, padrão: 1)
`transparent_background`	boolean	Usar fundo transparente (padrão: falso)
`color_mode`	string	`light`, `dark` ou `both` (padrão: `light`)
`width`	number	Largura em pixels (somente PNG, 100-10000)
`height`	number	Altura em pixels (somente PNG, 100-10000)
`orientation`	string	`auto`, `horizontal`, `vertical` ou `square`
`text_extraction_mode`	string	`auto`, `rewrite` ou `preserve` (padrão: `auto`)
`sort_strategy`	string	`relevance`, `random` ou `variation` (padrão: `relevance`)

Nota: visual_id/visual_ids e visual_query/visual_queries são mutuamente exclusivos.

Exemplo de Saída

Aqui estão alguns exemplos de visuais gerados usando este servidor MCP. Cada exemplo mostra o texto de entrada e o 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 visual gerado

Mind Map Example

### Fluxograma

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 gerado

Flowchart Example

Linha do tempo

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 gerado

Timeline Example

Veja mais exemplos na Galeria da Napkin AI.

Tipos de consulta visual

mindmap - Visualizações de mapa mental
flowchart - Fluxos de processo e diagramas
timeline - Eventos cronológicos
comparison - Comparações lado a lado
hierarchy - Estruturas organizacionais
cycle - Processos cíclicos
list - Listas com marcadores ou numeradas
matrix - Comparações em grade

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
}

Desenvolvimento

# 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

Solução de problemas

"NAPKIN_API_KEY is required"

Certifique-se de definir a variável de ambiente NAPKIN_API_KEY na sua configuração MCP.

"Storage not configured"

A ferramenta generate_and_save requer configuração de armazenamento. Adicione uma das configurações de armazenamento acima.

A geração de visuais expira

Aumente NAPKIN_MAX_WAIT_TIME (padrão: 300000ms = 5 minutos).

Problemas de conexão

Certifique-se de que o Node.js 18+ está instalado
Verifique se sua chave de API é válida
Verifique a conectividade de rede com api.napkin.ai

Referência da API

Site da Napkin AI
Galeria de Visuais - Veja exemplos de visuais gerados
Documentação da API
Estilos Disponíveis
Especificação MCP

Licença

MIT

Contribuição

Contribuições são bem-vindas! Leia nosso Guia de Contribuição antes de enviar pull requests.