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 许可证。

贡献

欢迎贡献！在提交拉取请求之前，请阅读我们的 贡献指南。