🎨 smart-excalidraw-mcp

用自然语言生成专业图表的 MCP Server

支持任意 OpenAI 兼容的 LLM API，兼容 Claude Code、Cursor、OpenCode 等所有 MCP 客户端

💡 产品哲学

传统的图表工具往往需要手动拖拽、调整，耗时且效率低下。smart-excalidraw-mcp 的诞生，源于对 "AI 原生工作流" 的探索：

• 自然语言即指令：你只需用文字描述想要的图表，AI 自动完成绘制。
• 22 种图表类型：从流程图到架构图，从思维导图到 ER 图，覆盖绝大多数可视化场景。
• 九象限箭头优化：自动优化箭头连接点，让图表更专业、更美观。
• 多模型支持：不绑定单一服务商，支持 OpenAI、Anthropic、阿里云、本地 LLM 等。
• 跨工具兼容：支持所有 MCP 协议客户端（Claude Code、Cursor、OpenCode 等）。

✨ 核心特性

| 特性 | 说明 | |------|------| | 🗣️ 自然语言交互 | 直接在 AI 对话中用文字描述想要的图表 | | 🎯 22 种图表类型 | 流程图、思维导图、架构图、ER 图、时序图等 | | ⚡ 高质量输出 | 九象限箭头优化算法，自动优化连接 | | 📦 开箱即用 | 支持任意 OpenAI 兼容 API | | 🔧 灵活配置 | 支持 OpenAI、Anthropic、本地 LLM 等 | | 🌐 跨工具兼容 | 支持 Claude Code、Cursor、OpenCode 等 MCP 客户端 | | 📝 Obsidian 兼容 | 输出 .excalidraw.md 格式，完美适配 Obsidian |

🚀 快速开始

1. 安装

# 克隆仓库
git clone https://github.com/linyuan3421/smart-excalidraw-mcp.git
cd smart-excalidraw-mcp

# 安装依赖
npm install

# 构建
npm run build

2. 配置 MCP 客户端

Claude Code

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/path/to/smart-excalidraw-mcp/dist/src/index.js"],
      "env": {
        "LLM_API_KEY": "your-api-key-here",
        "LLM_BASE_URL": "https://api.openai.com/v1",
        "LLM_MODEL": "gpt-4o"
      }
    }
  }
}

Cursor

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/path/to/smart-excalidraw-mcp/dist/src/index.js"],
      "env": {
        "LLM_API_KEY": "your-api-key-here",
        "LLM_BASE_URL": "https://api.openai.com/v1",
        "LLM_MODEL": "gpt-4o"
      }
    }
  }
}

OpenCode

在 opencode.json 中添加：

{
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["node", "/path/to/smart-excalidraw-mcp/dist/src/index.js"],
      "environment": {
        "LLM_API_KEY": "your-api-key-here",
        "LLM_BASE_URL": "https://api.openai.com/v1",
        "LLM_MODEL": "gpt-4o"
      }
    }
  }
}

其他 MCP 客户端

任何支持 Model Context Protocol 的客户端都可以使用本 MCP。配置格式基本一致，只需将 command 指向编译后的 dist/src/index.js 文件。

3. 重启你的 MCP 客户端

4. 开始使用

你: "帮我创建一个用户登录流程图"

AI: ✅ 自动调用 MCP → 生成图表 → 返回文件

⚙️ 环境变量配置

| 变量 | 说明 | 必填 | 默认值 | |------|------|------|--------| | LLM_API_KEY | LLM API 密钥 | ✅ | - | | LLM_BASE_URL | API 基础 URL | ❌ | https://api.openai.com/v1 | | LLM_MODEL | 模型名称 | ❌ | gpt-4o | | LLM_PROVIDER | 提供商类型 | ❌ | openai |

不同提供商配置

{
  "env": {
    "LLM_API_KEY": "sk-xxx",
    "LLM_BASE_URL": "https://api.openai.com/v1",
    "LLM_MODEL": "gpt-4o"
  }
}

{
  "env": {
    "LLM_API_KEY": "sk-ant-xxx",
    "LLM_BASE_URL": "https://api.anthropic.com/v1",
    "LLM_MODEL": "claude-sonnet-4-20250514"
  }
}

{
  "env": {
    "LLM_API_KEY": "ollama",
    "LLM_BASE_URL": "http://localhost:11434/v1",
    "LLM_MODEL": "llama3"
  }
}

{
  "env": {
    "LLM_API_KEY": "sk-xxx",
    "LLM_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "LLM_MODEL": "qwen-plus"
  }
}

📖 MCP 工具说明

generate_diagram

生成单个图表。

• text (必填) - 图表描述
• chartType (可选) - 图表类型，默认 auto
• outputPath (可选) - 输出文件路径

batch_generate_diagrams

批量生成图表。

• directory (必填) - 目录路径
• filePattern (可选) - 文件匹配模式，默认 *.md
• chartType (可选) - 图表类型
• concurrency (可选) - 并发数，默认 5

optimize_diagram

优化已有图表的箭头连接。

• inputPath (必填) - 输入文件路径
• outputPath (可选) - 输出文件路径

list_chart_types

列出所有支持的图表类型。

📊 支持的图表类型（22 种）

| 类型 | 说明 | 类型 | 说明 | |------|------|------|------| | auto | 自动识别 | flowchart | 流程图 | | mindmap | 思维导图 | hierarchy | 层级图 | | sequence | 时序图 | relationship | 关系图 | | er | ER 图 | comparison | 对比图 | | timeline | 时间线 | tree | 树形图 | | network | 网络拓扑图 | architecture | 架构图 | | dataflow | 数据流图 | state | 状态图 | | swimlane | 泳道图 | concept | 概念图 | | fishbone | 鱼骨图 | swot | SWOT 分析图 | | pyramid | 金字塔图 | funnel | 漏斗图 | | venn | 韦恩图 | matrix | 矩阵图 | | infographic | 信息图 | | |

🔧 开发

项目结构

smart-excalidraw-mcp/
├── src/
│   ├── index.ts      # MCP server 入口
│   └── client.ts     # Excalidraw 客户端
├── lib/
│   ├── prompts.js    # 提示词模板
│   ├── llm-client.js # LLM API 客户端
│   └── optimizeArrows.js # 箭头优化算法
├── dist/             # 编译输出
├── package.json
└── tsconfig.json

构建

npm run build

本地测试

npx @modelcontextprotocol/inspector node dist/src/index.js

🛠️ 技术栈

• Runtime: Node.js 18+
• Language: TypeScript 5.0
• Protocol: Model Context Protocol (MCP) 1.0
• Compression: LZ-String (Obsidian compatible)
• AI Integration: OpenAI Compatible Interface

🙏 致谢

本项目的核心实现借鉴自 smart-excalidraw-next，感谢原作者的开源贡献。

具体包括：

• 提示词系统 (lib/prompts.js) - 图表生成的 Prompt 工程
• 箭头优化算法 (lib/optimizeArrows.js) - 九象限箭头连接优化
• 图表类型定义 - 22 种图表类型及其说明

同时也感谢以下项目：

• Excalidraw - 强大的白板工具
• Model Context Protocol - MCP 协议

👨‍💻 关于作者

本项目由 [反时钟效率笔记] 设计与维护。

如果你喜欢这个项目，或者想获取更多 AI 相关的探索，欢迎关注我的公众号。

👆 扫码关注，让思考慢下来，让效率快起来。

🤝 贡献

欢迎提交 Issue 或 Pull Request！ 如果你喜欢这个项目，请给它一个 ⭐️ Star，这对我意义重大。

📄 许可证

MIT License.