Napkin Ai MCP

🚀 Napkin AI MCP 服務器

這是一個基於 Napkin AI API 的 MCP（模型上下文協議）服務器，可用於生成信息圖表和可視化內容。藉助該服務器，像 Claude 這樣的 AI 助手能夠根據文本內容生成專業的可視化圖表。

🚀 快速開始

前提條件

• 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@napkin.ai 申請 API 訪問權限

✨ 主要特性

• 可視化生成：根據文本內容生成 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 命令可查看使用說明。

📦 安裝指南

全局安裝

npm install -g napkin-ai-mcp

使用 npx 直接運行

npx napkin-ai-mcp

💻 使用示例

基礎用法

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",
});

// 使用生成文件的 URL 下載文件
if (result.generated_files && result.generated_files.length > 0) {
  const buffer = await client.downloadFile(result.generated_files[0].url);
  // buffer 包含 SVG 內容
}

📚 詳細文檔

集成指南

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，建議使用雲存儲提供商（如 S3、Google Drive 等），這些服務會返回可訪問的 URL。Claude Code 具有完整的文件系統訪問權限，可以與本地存儲無縫配合使用。

Amazon S3

將可視化圖表保存到 S3 存儲桶（也適用於兼容 S3 的服務，如 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/  # 可選路徑前綴
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. 與服務賬戶電子郵件（以 @*.iam.gserviceaccount.com 結尾）共享目標 Google Drive 文件夾。
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

通過 Webhook 將可視化圖表發送到 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"。

注意：無需設置機器人 - Webhook 是向 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 服務器生成的可視化圖表示例。每個示例都顯示了輸入文本和生成的可視化圖表。

思維導圖

輸入文本：

# 視覺傳達的好處

## 速度
- 處理速度比文本快 60,000 倍
- 即時模式識別

## 記憶
- 我們看到的內容有 80% 會被記住
- 只有 20% 的文本會被記住

## 參與度
- 比純文本內容多 94% 的瀏覽量
- 更高的社交分享率

參數：format: "svg", visual_query: "mindmap", language: "en-GB"

流程圖

輸入文本：

# 用戶註冊流程

1. 用戶點擊 "註冊" 按鈕
2. 輸入電子郵件地址
3. 系統驗證電子郵件格式
4. 如果格式無效，顯示錯誤消息
5. 如果格式有效，發送驗證電子郵件
6. 用戶點擊驗證鏈接
7. 創建密碼
8. 驗證密碼強度
9. 如果密碼強度足夠，創建賬戶
10. 重定向到儀表盤

參數：format: "svg", visual_query: "flowchart", language: "en-GB"

時間線

輸入文本：

# 人工智能歷史

## 1950 年
艾倫·圖靈發表 "Computing Machinery and Intelligence"

## 1956 年
"人工智能" 一詞被創造出來

## 1997 年
IBM 的深藍擊敗國際象棋世界冠軍

## 2016 年
AlphaGo 擊敗圍棋世界冠軍李世石

## 2022 年
ChatGPT 發佈，將大語言模型帶入主流

參數：format: "svg", visual_query: "timeline", language: "en-GB"

更多示例請查看 Napkin AI Gallery。

可視化查詢類型

• mindmap - 思維導圖可視化
• flowchart - 流程和圖表
• timeline - 按時間順序排列的事件
• comparison - 並排比較
• hierarchy - 組織結構
• cycle - 循環過程
• list - 項目符號或編號列表
• matrix - 基於網格的比較

🔧 技術細節

開發

# 克隆倉庫
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 網站
• 可視化示例庫 - 查看生成的可視化圖表示例
• API 文檔
• 可用樣式
• MCP 規範

📄 許可證

本項目採用 MIT 許可證。

貢獻

歡迎貢獻！在提交拉取請求之前，請閱讀我們的 貢獻指南。