Napkin Ai MCP

🚀 Napkin AI MCP

このサーバーは、Napkin AI APIを使用して、情報グラフィックやビジュアルを生成するためのMCP（Model Context Protocol）サーバーです。これにより、ClaudeなどのAIアシスタントが、テキストコンテンツから専門的なビジュアルを生成できるようになります。

⚠️ 重要提示

これは非公式の、コミュニティがメンテナンスするNapkin AIのMCPサーバーです。Napkin AIまたはSecond Layer, Inc.とは関係がなく、承認もされておらず、公式にサポートされていません。公式のNapkin AI製品とサポートについては、napkin.aiをご覧ください。

⚠️ 重要提示

API互換性：Napkin AI API v0.10.5でテストされています。新しいAPIバージョンでは破壊的な変更が導入される可能性があります。

🚀 クイックスタート

前提条件

• Node.js 18.x以降
• Napkin AI APIキー（現在は開発者プレビュー中 - api@napkin.aiに問い合わせてください）

インストール

npm install -g napkin-ai-mcp

または、npxを使用して直接実行することもできます：

npx napkin-ai-mcp

APIキーの取得

Napkin AI APIは現在開発者プレビュー中です。アクセスをリクエストするには：

1. napkin.aiにアクセスします。
2. APIアクセスのためにapi@napkin.aiに連絡します。

✨ 主な機能

• ビジュアル生成：テキストコンテンツからSVG、PNG、またはPPTのビジュアルを生成します。
• 複数のビジュアルタイプ：マインドマップ、フローチャート、タイムライン、比較表など（ギャラリーを参照）。
• 非同期処理：Napkin AIの非同期生成を自動的にポーリングします。
• 複数のストレージサポート：生成されたビジュアルを以下に保存できます：
  • ローカルファイルシステム
  • Amazon S3（またはS3互換サービス）
  • Google Drive
  • Slack
  • Notion
  • Telegram
  • Discord
• 柔軟な設定：環境変数またはJSON設定ファイルを使用します。
• 完全なTypeScriptサポート：Zod検証を備えた包括的な型定義があります。
• 自動リトライ：一時的な障害（429、5xx）に対して指数バックオフを行います。
• デバッグロギング：トラブルシューティングのためにNAPKIN_DEBUG=trueを設定します。
• ドライランモード：APIを呼び出さずにリクエストを検証します。
• CLIヘルプ：--helpを指定して実行すると、使用方法が表示されます。

📦 インストール

各種アプリケーションへの統合ガイド

Claude Desktop

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

ローカルストレージを有効にする場合：

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

設定を更新したら、Claude Desktopを再起動します。

Claude Code (CLI)

Claude CodeのMCP設定に追加します：

• グローバル設定：~/.claude/settings.json
• プロジェクト設定：.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"
      }
    }
  }
}

または、CLIコマンドを実行します：

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

その後、環境変数を設定します：

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

Cursor

CursorのMCP設定に追加します：

• ファイル：~/.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

WindsurfのMCP設定に追加します：

• ファイル：~/.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

Continueの設定に追加します：

• ファイル：~/.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)

VS CodeのCline MCP設定に追加します：

1. VS Codeの設定を開きます。
2. "Cline MCP"を検索します。
3. サーバー設定を追加します：

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

💻 使用例

利用可能なツール

設定が完了すると、AIアシスタントは以下のツールにアクセスできます：

サンプルプロンプト

設定が完了したら、AIアシスタントに以下のプロンプトを試してみてください：

• "機械学習の主要な概念を視覚化したマインドマップを作成してください"
• "ユーザー登録プロセスを示すフローチャートを生成してください"
• "コンピューターの歴史における主要なイベントのタイムラインを作成してください"
• "RESTとGraphQL APIを比較する情報グラフィックを作成してください"

📚 ドキュメント

設定

環境変数

ストレージ設定

ローカルストレージ

ビジュアルをローカルディレクトリに保存します：

NAPKIN_STORAGE_TYPE=local
NAPKIN_STORAGE_LOCAL_DIR=./output

ファイルはnapkin-{request_id}-{index}-{color_mode}.{format}の形式で保存されます。

⚠️ 重要提示

Claude Desktopのユーザーへの注意：Claude Desktopはサンドボックス環境で実行されるため、ローカルファイルシステムのパスにアクセスできません。ファイルは正常に保存されますが、Claude Desktopは直接表示または開くことができません。Claude Desktopの場合は、アクセス可能なURLを返すクラウドストレージプロバイダー（S3、Google Driveなど）を使用することを検討してください。Claude Codeは完全なファイルシステムアクセスを持っており、ローカルストレージとシームレスに動作します。

Amazon S3

ビジュアルをS3バケットに保存します（MinIO、DigitalOcean Spaces、Cloudflare R2などのS3互換サービスでも動作します）：

NAPKIN_STORAGE_TYPE=s3
NAPKIN_STORAGE_S3_BUCKET=my-bucket
NAPKIN_STORAGE_S3_REGION=eu-west-1
NAPKIN_STORAGE_S3_PREFIX=napkin-visuals/  # オプションのパスプレフィックス
NAPKIN_STORAGE_S3_ENDPOINT=https://s3.example.com  # オプション、S3互換サービス用
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

必要なIAMパーミッション：

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

Google Drive

サービスアカウントを使用して、ビジュアルをGoogle Driveのフォルダに保存します：

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

セットアップ手順：

1. Google Cloud Consoleにアクセスします。
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
3. Google Drive APIを有効にします。
4. "IAM & Admin" → "Service Accounts" → "Create Service Account"に移動します。
5. JSONキーファイルをダウンロードし、service-account.jsonとして保存します。
6. ターゲットのGoogle Driveフォルダをサービスアカウントのメールアドレス（@*.iam.gserviceaccount.comで終わる）と共有します。
7. URLからフォルダIDを取得します：https://drive.google.com/drive/folders/{FOLDER_ID}

Slack

ビジュアルをSlackチャンネルにアップロードします：

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

セットアップ手順：

1. Slack APIにアクセスし、新しいアプリを作成します。
2. "OAuth & Permissions"の下で、以下のBot Token Scopesを追加します：
   • files:write - ファイルをアップロードする
   • chat:write - メッセージを投稿する（オプション）
3. アプリをワークスペースにインストールします。
4. "Bot User OAuth Token"（xoxb-で始まる）をコピーします。
5. チャンネルIDを取得します：チャンネルを右クリック → "View channel details" → 一番下までスクロール

注意：ボットは/invite @your-bot-nameでチャンネルに招待する必要があります。

Notion

ビジュアルを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  # オプション

セットアップ手順：

1. Notion Integrationsにアクセスし、新しい統合を作成します。
2. "Internal Integration Token"（secret_で始まる）をコピーします。
3. ターゲットのNotionページを開き、"..." → "Add connections" → 統合を選択します。
4. URLからページIDを取得します：https://notion.so/Page-Name-{PAGE_ID}（末尾の32文字のID）

注意：Notionにはファイルサイズ制限があります。大きなビジュアルの場合は、S3またはGoogle Driveを使用することを検討してください。

Telegram

ビジュアルをTelegramチャットまたはチャンネルに送信します：

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

セットアップ手順：

1. Telegramで@BotFatherにメッセージを送り、/newbotで新しいボットを作成します。
2. ボットトークン（形式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）をコピーします。
3. ボットをグループ/チャンネルに管理者（チャンネルの場合）またはメンバー（グループの場合）として追加します。
4. チャットIDを取得します：
   • グループの場合：@userinfobotをグループに追加すると、チャットIDが表示されます。
   • チャンネルの場合：チャンネルからのメッセージを@userinfobotに転送します。
   • プライベートチャットの場合：ボットにメッセージを送信し、https://api.telegram.org/bot<TOKEN>/getUpdatesにアクセスします。

注意：チャンネルIDは-100で始まり、グループIDは負の数、ユーザーIDは正の数です。

Discord

ウェブフックを介して、ビジュアルをDiscordチャンネルに送信します：

NAPKIN_STORAGE_TYPE=discord
NAPKIN_STORAGE_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/123456789/abcdef...
NAPKIN_STORAGE_DISCORD_USERNAME=Napkin AI  # オプション

セットアップ手順：

1. Discordを開き、ビジュアルを受信するチャンネルに移動します。
2. 歯車アイコン（Edit Channel） → Integrations → Webhooks → New Webhookをクリックします。
3. 名前を付け、必要に応じてアバターをアップロードします。
4. "Copy Webhook URL"をクリックします。

注意：ボットのセットアップは必要ありません - ウェブフックはDiscordに投稿する最も簡単な方法です。

デフォルトのビジュアル設定

NAPKIN_DEFAULT_FORMAT=svg       # svg、png、またはppt
NAPKIN_DEFAULT_LANGUAGE=en-GB   # BCP 47言語タグ
NAPKIN_DEFAULT_COLOR_MODE=light # light、dark、またはboth
NAPKIN_DEFAULT_ORIENTATION=auto # auto、horizontal、vertical、またはsquare

JSON設定

config.jsonファイルを作成します：

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

ツールパラメータ

generate_visual / generate_and_wait / generate_and_save

注意：visual_id/visual_idsとvisual_query/visual_queriesは相互に排他的です。

出力例

ここでは、このMCPサーバーを使用して生成されたビジュアルの例をいくつか示します。各例では、入力テキストと生成されたビジュアルを表示します。

マインドマップ

入力テキスト：

# 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

パラメータ：format: "svg", visual_query: "mindmap", language: "en-GB"

フローチャート

入力テキスト：

# 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

パラメータ：format: "svg", visual_query: "flowchart", language: "en-GB"

タイムライン

入力テキスト：

# 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

パラメータ：format: "svg", visual_query: "timeline", language: "en-GB"

Napkin AI Galleryでさらに多くの例を見ることができます。

ビジュアルクエリタイプ

• mindmap - マインドマップの視覚化
• flowchart - プロセスフローとダイアグラム
• timeline - 時系列イベント
• comparison - 並列比較
• hierarchy - 組織構造
• cycle - 循環プロセス
• list - 箇条書きまたは番号付きリスト
• matrix - グリッドベースの比較

プログラムによる使用方法

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

// クライアントを直接使用する
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",
});

// generated_filesからURLを使用してファイルをダウンロードする
if (result.generated_files && result.generated_files.length > 0) {
  const buffer = await client.downloadFile(result.generated_files[0].url);
  // bufferにはSVGコンテンツが含まれている
}

🔧 技術詳細

開発

# リポジトリをクローンする
git clone https://github.com/LouisChanCLY/napkin-ai-mcp.git
cd napkin-ai-mcp

# 依存関係をインストールする
npm install

# 開発モードで実行する
npm run dev

# テストを実行する
npm test

# 本番用にビルドする
npm run build

トラブルシューティング

"NAPKIN_API_KEY is required"

MCP設定でNAPKIN_API_KEY環境変数が設定されていることを確認してください。

"Storage not configured"

generate_and_saveツールにはストレージ設定が必要です。上記のストレージ設定のいずれかを追加してください。

ビジュアル生成がタイムアウトする

NAPKIN_MAX_WAIT_TIMEを増やしてください（デフォルト：300000ms = 5分）。

接続問題

1. Node.js 18以上がインストールされていることを確認します。
2. APIキーが有効であることを確認します。
3. api.napkin.aiへのネットワーク接続を確認します。

APIリファレンス

• Napkin AI Website
• Visual Gallery - 生成されたビジュアルの例を見ることができます
• API Documentation
• Available Styles
• MCP Specification

📄 ライセンス

MIT

貢献

貢献は大歓迎です！プルリクエストを送信する前に、Contributing Guideをお読みください。