Napkin Ai MCP

🚀 Napkin AI MCP Server

This is an MCP (Model Context Protocol) server that uses the Napkin AI API to generate infographics and visuals. It enables AI assistants like Claude to create professional visuals from text content.

⚠️ Important Note

This is an unofficial, community-maintained MCP server for Napkin AI. It is not affiliated with, endorsed by, or officially supported by Napkin AI or Second Layer, Inc. For official Napkin AI products and support, please visit napkin.ai.

⚠️ Important Note

API Compatibility: Tested with Napkin AI API v0.10.5. Newer API versions may introduce breaking changes.

🚀 Quick Start

Prerequisites

• Node.js 18.x or later
• A Napkin AI API key (currently in developer preview - contact api@napkin.ai)

Installation

npm install -g napkin-ai-mcp

Or use directly with npx:

npx napkin-ai-mcp

Get Your API Key

The Napkin AI API is currently in developer preview. To request access:

1. Visit napkin.ai
2. Contact api@napkin.ai for API access

✨ Features

• Visual Generation: Generate SVG, PNG, or PPT visuals from text content
• Multiple Visual Types: Mindmaps, flowcharts, timelines, comparisons, and more (see gallery)
• Async Handling: Automatic polling for Napkin AI's async generation
• Multi-Storage Support: Save generated visuals to local filesystem, Amazon S3 (or S3-compatible services), Google Drive, Slack, Notion, Telegram, or Discord
• Flexible Configuration: Environment variables or JSON config file
• Full TypeScript Support: Comprehensive type definitions with Zod validation
• Automatic Retries: Exponential backoff for transient failures (429, 5xx)
• Debug Logging: Set NAPKIN_DEBUG=true for troubleshooting
• Dry-Run Mode: Validate requests without calling the API
• CLI Help: Run with --help for usage information

📦 Installation

Global Installation

npm install -g napkin-ai-mcp

Using npx

npx napkin-ai-mcp

💻 Usage Examples

Claude Desktop

Add to your Claude Desktop configuration file: 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"
      }
    }
  }
}

With local storage enabled:

{
  "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"
      }
    }
  }
}

After updating the config, restart Claude Desktop.

Claude Code (CLI)

Add to your Claude Code MCP settings: Global config: ~/.claude/settings.json Project config: .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"
      }
    }
  }
}

Or run the CLI command:

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

Then set the environment variable:

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

Cursor

Add to your Cursor MCP configuration: File: ~/.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

Add to your Windsurf MCP configuration: File: ~/.windsurf/mcp.json

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

VS Code with Continue

Add to your Continue configuration: File: ~/.continue/config.json

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

Cline (VS Code Extension)

Add to your Cline MCP settings in VS Code:

1. Open VS Code settings
2. Search for "Cline MCP"
3. Add the server configuration:

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

📚 Documentation

Available Tools

Once configured, your AI assistant will have access to these tools:

Example Prompts

Once configured, try these prompts with your AI assistant:

• "Create a mindmap visualising the key concepts of machine learning"
• "Generate a flowchart showing the user registration process"
• "Make a timeline of major events in the history of computing"
• "Create an infographic comparing REST vs GraphQL APIs"

Configuration

Environment Variables

Storage Configuration

Local Storage

NAPKIN_STORAGE_TYPE=local
NAPKIN_STORAGE_LOCAL_DIR=./output

Files are saved with the format: napkin-{request_id}-{index}-{color_mode}.{format}

⚠️ Important Note

Claude Desktop runs in a sandboxed environment and cannot access local filesystem paths. While files are saved successfully, Claude Desktop cannot display or open them directly. For Claude Desktop, consider using a cloud storage provider (S3, Google Drive, etc.) which returns accessible URLs. Claude Code has full filesystem access and works seamlessly with local storage.

Amazon S3

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

Required IAM permissions:

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

Google Drive

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

Setup steps:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Drive API
4. Go to "IAM & Admin" → "Service Accounts" → "Create Service Account"
5. Download the JSON key file and save as service-account.json
6. Share your target Google Drive folder with the service account email (ends with @*.iam.gserviceaccount.com)
7. Get the folder ID from the URL: https://drive.google.com/drive/folders/{FOLDER_ID}

Slack

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

Setup steps:

1. Go to Slack API and create a new app
2. Under "OAuth & Permissions", add these Bot Token Scopes:
   • files:write - Upload files
   • chat:write - Post messages (optional)
3. Install the app to your workspace
4. Copy the "Bot User OAuth Token" (starts with xoxb-)
5. Get the channel ID: right-click a channel → "View channel details" → scroll to the bottom

⚠️ Important Note

The bot must be invited to the channel with /invite @your-bot-name

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

Setup steps:

1. Go to Notion Integrations and create a new integration
2. Copy the "Internal Integration Token" (starts with secret_)
3. Open the target Notion page and click "..." → "Add connections" → select your integration
4. Get the page ID from the URL: https://notion.so/Page-Name-{PAGE_ID} (the 32-character ID at the end)

⚠️ Important Note

Notion has file size limits. For large visuals, consider using S3 or Google Drive.

Telegram

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

Setup steps:

1. Message @BotFather on Telegram and create a new bot with /newbot
2. Copy the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
3. Add the bot to your group/channel as an admin (for channels) or member (for groups)
4. Get the chat ID:
   • For groups: Add @userinfobot to the group, it will show the chat ID
   • For channels: Forward a message from the channel to @userinfobot
   • For private chats: Send a message to your bot, then visit https://api.telegram.org/bot<TOKEN>/getUpdates

⚠️ Important Note

Channel IDs start with -100, group IDs are negative numbers, user IDs are positive.

Discord

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

Setup steps:

1. Open Discord and go to the channel where you want to receive visuals
2. Click the gear icon (Edit Channel) → Integrations → Webhooks → New Webhook
3. Give it a name and optionally upload an avatar
4. Click "Copy Webhook URL"

⚠️ Important Note

No bot setup required - webhooks are the simplest way to post to Discord.

Default Visual Settings

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

JSON Configuration

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

Tool Parameters

generate_visual / generate_and_wait / generate_and_save

⚠️ Important Note

visual_id/visual_ids and visual_query/visual_queries are mutually exclusive.

Example Output

Mind Map

Input text:

# 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

Parameters: format: "svg", visual_query: "mindmap", language: "en-GB"

Flowchart

Input text:

# 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

Parameters: format: "svg", visual_query: "flowchart", language: "en-GB"

Timeline

Input text:

# 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

Parameters: format: "svg", visual_query: "timeline", language: "en-GB"

See more examples at the Napkin AI Gallery.

Visual Query Types

• mindmap - Mind map visualisations
• flowchart - Process flows and diagrams
• timeline - Chronological events
• comparison - Side-by-side comparisons
• hierarchy - Organisational structures
• cycle - Cyclical processes
• list - Bulleted or numbered lists
• matrix - Grid-based comparisons

Programmatic Usage

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
}

🔧 Technical Details

Development

# 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

Troubleshooting

"NAPKIN_API_KEY is required"

Ensure you've set the NAPKIN_API_KEY environment variable in your MCP configuration.

"Storage not configured"

The generate_and_save tool requires storage configuration. Add one of the storage configurations above.

Visual generation times out

Increase NAPKIN_MAX_WAIT_TIME (default: 300000ms = 5 minutes).

Connection issues

1. Ensure Node.js 18+ is installed
2. Check your API key is valid
3. Verify network connectivity to api.napkin.ai

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide before submitting pull requests.

📚 API Reference

• Napkin AI Website
• Visual Gallery - See examples of generated visuals
• API Documentation
• Available Styles
• MCP Specification