Napkin AI MCP

免责声明： 这是一个 非官方的，社区维护的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密钥（目前正在开发者预览-联系方式 )

快速开始

安装

npm install -g napkin-ai-mcp

或者直接与npx一起使用：

npx napkin-ai-mcp

获取API密钥

Napkin AI API目前正在开发者预览中。要请求访问权限，请执行以下操作：

1. 访问 napkin.ai
2. 联系 用于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设置中：

1. 打开VS代码设置
2. 搜索“临床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具有完全的文件系统访问权限，并与本地存储无缝协作。

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

设置步骤：

1. 首选 谷歌云控制台
2. 创建新项目或选择现有项目
3. 启用Google Drive API
4. 转到“IAM和管理员”→ “服务帐户”→ “创建服务帐户”
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. 首选 松弛API 并创建新应用程序
2. 在“OAuth和权限”下，添加以下Bot令牌范围：

- files:write -上传文件 - chat:write -发布消息（可选）

1. 将应用程序安装到您的工作区
2. 复制“Bot用户OAuth令牌”（以开头 xoxb-)
3. 获取通道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

设置步骤：

1. 首选 概念整合 并创建新的集成
2. 复制“内部集成令牌”（以开头 secret_)
3. 打开目标Notion页面，点击“…”→“添加连接”→ 选择您的集成
4. 从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

设置步骤：

1. 消息 @植物学家 在Telegram上创建一个新的机器人 /newbot
2. 复制机器人令牌（格式： 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
3. 将机器人作为管理员（用于频道）或成员（用于群组）添加到您的群组/频道
4. 获取聊天ID:

- 对于 群组：添加 @用户信息机器人 对于群，它将显示聊天ID - 对于 频道：将消息从频道转发到 @用户信息机器人 - 对于 私人聊天：向您的机器人发送消息，然后访问 https://api.telegram.org/bot/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

设置步骤：

1. 打开Discord，转到要接收视觉效果的频道
2. 点击齿轮图标（编辑频道）→ 集成→ 网络钩子→ 新Webhook
3. 为其命名，并可选择上传头像
4. 点击“复制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"
  }
}

______________________________________________________________________

刀具参数

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

备注: 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分钟）。

连接问题

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

______________________________________________________________________

API 参考

• Napkin人工智能网站
• 视觉画廊 -查看生成的视觉效果示例
• API文档
• 可用样式
• MCP规范

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

贡献

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