使用说明

免责声明： 这是一个 非官方的，社区维护的Napkin AI MCP服务器。它不隶属于Napkin人工智能或Second Layer，股份有限公司，也不由其认可或正式支持。有关Napkin的官方人工智能产品和支持，请访问 napkin.ai.

API兼容性： 使用Napkin AI API v1.1.16进行测试。较新的API版本可能会引入突破性的更改。

MCP（模型上下文协议）服务器，用于使用 Napkin AI API该服务器使像克劳德这样的人工智能助手能够从文本内容中生成专业视觉效果。

特性

视觉生成：从文本内容生成SVG、PNG或PPT视觉效果
多种视觉类型：思维导图、流程图、时间线、比较等(查看图库)
异步处理：Napkin AI异步生成的自动轮询
多存储支持：将生成的视觉效果保存到：
- 本地文件系统
- Amazon S3（或与S3兼容的服务）
- Google 云端硬盘
- Slack
- 概念
- 电报
- Discord 的中文翻译是“不和谐”或“纷争”。
灵活配置：环境变量或JSON配置文件
完全支持TypeScript：具有Zod验证的全面类型定义
自动检索：瞬态故障的指数回退（429，5xx）
调试日志记录：设置 NAPKIN_DEBUG=true 故障排除
干运行模式：在不调用API的情况下验证请求
CLI帮助：跑步 --help 有关使用信息

先决条件

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目前正在开发者预览中。要请求访问权限，请执行以下操作：

访问 napkin.ai
联系 api@napkin.ai 用于API访问

集成指南

克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %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。

克劳德代码（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"

光标

添加到光标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 MCP配置中：

文件: ~/.windsurf/mcp.json

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

VS代码并继续

添加到“继续”配置中：

文件: ~/.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代码扩展）

在VS Code中添加到您的临床MCP设置中：

打开VS代码设置
搜索“临床MCP”
添加服务器配置：

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

可用工具

配置后，您的AI助手将可以访问这些工具：

工具	说明
`generate_visual`	提交可视化生成请求（异步）
`check_status`	检查生成请求的状态
`download_visual`	将生成的可视化文件下载为base64
`generate_and_wait`	生成并等待完成
`generate_and_save`	生成并保存到配置的存储
`list_styles`	获取有关可用样式的信息
`verify_api_key`	验证您的API密钥有效且有效

示例提示

配置后，请使用您的AI助手尝试以下提示：

“创建一个思维导图，将机器学习的关键概念可视化”
“生成显示用户注册过程的流程图”
“制定计算史上重大事件的时间表”
“创建一个比较REST与GraphQL API的信息图”

配置

环境变量

变量	描述	必填
`NAPKIN_API_KEY`	Napkin AI API密钥	是
`NAPKIN_API_BASE_URL`	自定义API基础URL	否
`NAPKIN_STORAGE_TYPE`	存储类型： `local`, `s3`, `google-drive`, `slack`, `notion`, `telegram`, `discord`	没有
`NAPKIN_POLLING_INTERVAL`	轮询间隔（毫秒）（默认值：2000）	否
`NAPKIN_MAX_WAIT_TIME`	最大等待时间（毫秒）（默认值：300000）	否

存储配置

本地存储

将视觉效果保存到本地目录：

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具有完全的文件系统访问权限，并与本地存储无缝协作。

亚马逊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/  # 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

所需IAM权限：

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

Google 云端硬盘

使用服务帐户将视觉效果保存到Google Drive文件夹：

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

设置步骤：

首选谷歌云控制台
创建新项目或选择现有项目
启用Google Drive API
转到“IAM和管理员”→ “服务帐户”→ “创建服务帐户”
下载JSON密钥文件并另存为 service-account.json
将您的目标Google Drive文件夹与服务帐户电子邮件共享（以结尾 @*.iam.gserviceaccount.com)
从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

设置步骤：

首选松弛API 并创建新应用程序
在“OAuth和权限”下，添加以下Bot令牌范围：
- files:write -上传文件
- chat:write -发布消息（可选）
将应用程序安装到您的工作区
复制“Bot用户OAuth令牌”（以开头 xoxb-)
获取通道ID：右键单击通道→ “查看频道详细信息”→ 滚动到底部

注：必须邀请机器人加入频道 /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

设置步骤：

首选概念整合并创建新的集成
复制“内部集成令牌”（以开头 secret_)
打开目标Notion页面，点击“…”→“添加连接”→ 选择您的集成
从URL获取页面ID： https://notion.so/Page-Name-{PAGE_ID} （末尾的32个字符的ID）

注： Notion有文件大小限制。对于大型视觉效果，请考虑使用S3或Google Drive。

电报

将视觉效果发送到Telegram聊天或频道：

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

设置步骤：

消息 @植物学家在Telegram上创建一个新的机器人 /newbot
复制机器人令牌（格式： 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
将机器人作为管理员（用于频道）或成员（用于群组）添加到您的群组/频道
获取聊天ID:
- 对于群组：添加 @用户信息机器人对于群，它将显示聊天ID
- 对于频道：将消息从频道转发到 @用户信息机器人
- 对于 私人聊天：向您的机器人发送消息，然后访问 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  # Optional

设置步骤：

打开Discord，转到要接收视觉效果的频道
点击齿轮图标（编辑频道）→ 集成→ 网络钩子→ 新Webhook
为其命名，并可选择上传头像
点击“复制Webhook URL”

注：无需设置机器人程序——webhooks是发布到Discord的最简单方法。

默认视觉设置

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配置

创建一个 config.json 文件：

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

刀具参数

生成可视化/生成等待/生成保存

参数	类型	说明
`content`	字符串	必需.要可视化的文本内容
`format`	string	输出格式： `svg`, `png`，或 `ppt` （默认值： `svg`)
`dry_run`	boolean	在不调用API的情况下验证请求（默认值： `false`)
`context`	string	用于生成的附加上下文（未在视觉中显示）
`language`	string	BCP 47语言标签（例如。， `en-GB`).违约： `en`
`style_id`	string	餐巾纸AI样式标识符。看样式
`visual_id`	string	用新内容重新生成特定的视觉布局
`visual_ids`	string[]	视觉ID数组（长度必须匹配 `number_of_visuals`)
`visual_query`	string	视觉类型： `mindmap`, `flowchart`, `timeline`等等。
`visual_queries`	string[]	视觉查询数组（长度必须匹配 `number_of_visuals`)
`number_of_visuals`	number	要生成的变量（1-4，默认值：1）
`transparent_background`	boolean	使用透明背景（默认值：false）
`color_mode`	字符串	`light`, `dark`，或 `both` （默认值： `light`)
`width`	number	宽度（像素）（仅PNG，100-10000）
`height`	number	高度（像素）（仅PNG，100-10000）
`orientation`	字符串	`auto`, `horizontal`, `vertical`，或 `square`
`text_extraction_mode`	字符串	`auto`, `rewrite`，或 `preserve` （默认值： `auto`)
`sort_strategy`	字符串	`relevance`, `random`，或 `variation` （默认值： `relevance`)

备注: 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"

View generated visual

流程图

输入文本：

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

View generated visual

时间线

输入文本：

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

View generated visual

更多示例请访问 Napkin AI画廊.

可视化查询类型

mindmap -思维导图可视化
flowchart -工艺流程和图表
timeline -按时间顺序排列的事件
comparison -并排比较
hierarchy -组织结构
cycle -循环过程
list -项目符号或编号列表
matrix -基于网格的比较

程序化使用

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
}

发展

# 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

故障排除

“NAPKIN_API_KEY是必需的”

确保您已设置 NAPKIN_API_KEY MCP配置中的环境变量。

“存储未配置”

这 generate_and_save 该工具需要存储配置。添加上述存储配置之一。

视觉生成超时

增加 NAPKIN_MAX_WAIT_TIME （默认值：300000ms=5分钟）。

连接问题

确保已安装Node.js 18+
检查您的API密钥是否有效
验证与api.napkin.ai的网络连接

API 参考

许可证

麻省理工学院

贡献

欢迎投稿！请阅读我们的贡献指南在提交pull请求之前。

使用说明

特性

先决条件

快速开始

安装

获取API密钥

集成指南

克劳德桌面版

克劳德代码（CLI）

光标

帆板运动

VS代码并继续

Cline（VS代码扩展）

可用工具

示例提示

配置

环境变量

存储配置

本地存储

亚马逊S3

Google 云端硬盘

Slack

概念

电报

Discord 的中文翻译是“不和谐”或“纷争”。

默认视觉设置

JSON配置

刀具参数

生成可视化/生成等待/生成保存

输出示例

思维导图

流程图

时间线

可视化查询类型

程序化使用

发展

故障排除

“NAPKIN_API_KEY是必需的”

“存储未配置”

视觉生成超时

连接问题

API 参考

许可证

贡献

相关 MCP

Rhino与Grasshopper AI控制MCP服务

Blender 3D建模MCP服务

PCB设计自动化MCP服务器

3D资产生成服务

Markdown转思维导图服务

AntV文档协议服务器