miro-mcp-server

🚀 Miro MCP Server

借助人工智能控制 Miro 白板。采用Go语言构建，兼具速度与简洁性。

社区项目 — 本项目与Miro官方无直接关联。请查看下方的 官方版本与社区版本对比。

77 种工具 | 单二进制文件 | 全平台支持 | 支持所有主流AI工具

🚀 快速开始

1. 安装

Homebrew（macOS/Linux）：

brew tap olgasafonova/tap && brew install miro-mcp-server

单行命令（macOS/Linux）：

curl -fsSL https://raw.githubusercontent.com/olgasafonova/miro-mcp-server/main/install.sh | sh

Docker：

docker pull ghcr.io/olgasafonova/miro-mcp-server:latest

手动下载：所有平台的安装说明请参考 SETUP.md

2. 获取 Miro 令牌

1. 访问 miro.com/app/settings/user-profile/apps
2. 创建一个具有 boards:read 和 boards:write 权限的应用
3. 将应用安装到您的团队，并复制令牌

3. 配置您的 AI 工具

Claude Code：

claude mcp add miro -e MIRO_ACCESS_TOKEN=your-token -- miro-mcp-server

Claude Desktop / Cursor / VS Code：配置说明请参考 SETUP.md

✨ 主要特性

可执行操作

| 类别 | 示例 | |------|------| | 白板操作 | 创建、复制、删除、更新、共享白板，列出成员 | | 元素操作 | 便签、形状、文本、卡片、应用卡片、框架 | | 图表生成 | 根据 Mermaid 语法生成流程图和序列图 | | 思维导图 | 创建具有父子关系的思维导图节点 | | 批量操作 | 一次性创建多个元素，创建便签网格 | | 标签管理 | 创建、附加、更新和组织标签 | | 分组管理 | 分组、取消分组、列出和管理元素组 | | 连接操作 | 使用带样式的箭头连接元素 | | 导出功能 | 白板缩略图，PDF/SVG 导出（企业版） |

语音操作示例

• "添加一个黄色便签，内容为 'Review PRs'"
• "创建一个流程图：开始 → 决策 → 结束"
• "我有哪些白板？"
• "将设计白板共享给 jane@example.com"
• "以 '项目想法' 为根节点创建一个思维导图"

📦 安装指南

安装方式

• Homebrew（macOS/Linux）：运行 brew tap olgasafonova/tap && brew install miro-mcp-server
• 单行命令（macOS/Linux）：运行 curl -fsSL https://raw.githubusercontent.com/olgasafonova/miro-mcp-server/main/install.sh | sh
• Docker：运行 docker pull ghcr.io/olgasafonova/miro-mcp-server:latest
• 手动下载：所有平台的安装说明请参考 SETUP.md

获取 Miro 令牌

1. 访问 miro.com/app/settings/user-profile/apps
2. 创建一个具有 boards:read 和 boards:write 权限的应用
3. 将应用安装到您的团队，并复制令牌

配置 AI 工具

• Claude Code：运行 claude mcp add miro -e MIRO_ACCESS_TOKEN=your-token -- miro-mcp-server
• Claude Desktop / Cursor / VS Code：配置说明请参考 SETUP.md

💻 使用示例

基础用法

您可以使用以下命令进行基本操作，例如获取 Miro 令牌和配置 AI 工具：

# 获取 Miro 令牌
# 1. 访问 [miro.com/app/settings/user-profile/apps](https://miro.com/app/settings/user-profile/apps)
# 2. 创建一个具有 `boards:read` 和 `boards:write` 权限的应用
# 3. 将应用安装到您的团队，并复制令牌

# 配置 Claude Code
claude mcp add miro -e MIRO_ACCESS_TOKEN=your-token -- miro-mcp-server

高级用法

图表生成

创建流程图和序列图，使用 Mermaid 语法：

流程图示例：

flowchart TB
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Retry]
    D --> B

序列图示例：

sequenceDiagram
    Alice->>Bob: Hello Bob!
    Bob-->>Alice: Hi Alice!

支持的语法：flowchart/graph、sequenceDiagram、方向（TB/LR/BT/RL）、形状（[] 矩形、{} 菱形、(()) 圆形）、带标签的边。

📚 详细文档

| 文档 | 描述 | |------|------| | QUICKSTART.md | 两分钟快速上手 | | SETUP.md | 所有 AI 工具的完整设置 | | CONFIG.md | 配置参考 | | PERFORMANCE.md | 优化指南 | | CHANGELOG.md | 版本历史 | | ERRORS.md | 错误处理与故障排除 |

🔧 技术细节

77 种工具详情

性能优化

• 缓存机制：2 分钟的 TTL 减少 API 调用
• 速率限制：自适应 Miro 的速率限制头
• 熔断机制：隔离故障端点
• 并行批量操作：并发创建元素
• 令牌验证：启动时快速失败并给出明确错误信息
• 临时错误重试：自动重试 502/503/504 错误并进行退避处理

更多优化提示和基准测试请参考 PERFORMANCE.md。

HTTP 模式端点

当使用 -http :8080 运行时：

| 端点 | 描述 | |------|------| | / | MCP 协议（可流式 HTTP） | | /health | 健康检查（JSON） | | /health?deep=true | 深度健康检查（测试 Miro API） | | /metrics | Prometheus 指标 |

健康检查响应示例：

{
  "status": "healthy",
  "server": "miro-mcp-server",
  "version": "1.9.0",
  "uptime": "2h30m",
  "components": {
    "config": {"status": "healthy"},
    "miro_api": {"status": "healthy", "latency": "145ms"}
  }
}

开发相关

# 构建项目
make build

# 运行测试
make test

# 运行带覆盖率的测试
make test-cover

# 代码检查
make lint

# 为所有平台构建
make build-all

# 查看所有目标
make help

Docker 部署

快速启动：

# 使用 docker-compose
export MIRO_ACCESS_TOKEN=your-token
docker-compose up -d

# 或者手动构建和运行
docker build -t miro-mcp-server .
docker run -e MIRO_ACCESS_TOKEN=xxx -p 8080:8080 miro-mcp-server

docker-compose.yml 特性：

• 配置了健康检查
• 资源限制模板
• 环境变量传递

使用 MCP Inspector 调试

使用 MCP Inspector 进行交互式测试和调试：

# 安装并运行（无需设置）
npx @modelcontextprotocol/inspector miro-mcp-server

# 使用环境变量运行
MIRO_ACCESS_TOKEN=your-token npx @modelcontextprotocol/inspector miro-mcp-server

打开 http://localhost:6274 可以：

• 浏览所有 77 种工具及其架构
• 交互式测试工具调用
• 查看原始 JSON-RPC 消息
• 调试参数验证

更多调试选项请参考 SETUP.md。

支持的平台

| 平台 | 二进制文件 | |------|------| | macOS（Apple Silicon） | miro-mcp-server-darwin-arm64 | | macOS（Intel） | miro-mcp-server-darwin-amd64 | | Linux（x64） | miro-mcp-server-linux-amd64 | | Linux（ARM64） | miro-mcp-server-linux-arm64 | | Windows（x64） | miro-mcp-server-windows-amd64.exe | | Docker | ghcr.io/olgasafonova/miro-mcp-server |

支持的 AI 工具

| 工具 | 状态 | |------|------| | Claude Code | 已测试 | | Claude Desktop | 已测试 | | Cursor | 已测试 | | VS Code + GitHub Copilot | 支持 | | Windsurf | 支持 | | Replit | 支持 | | 任何 MCP 兼容客户端 | 支持 |

配置指南请参考 SETUP.md。

账户兼容性

| 账户类型 | 支持情况 | |------|------| | 免费版 | 完全访问所有 77 种工具 | | 团队版 | 完全访问所有 77 种工具 | | 商业版 | 完全访问所有 77 种工具 | | 企业版 | 完全访问 + PDF/SVG 导出 |

与其他方案对比

与 TypeScript 替代方案对比

| 特性 | 本服务器 | TypeScript 替代方案 | |------|------|------| | 运行时 | 单二进制文件 | 需要 Node.js | | 大小 | 约 14MB | 包含 node_modules 时超过 100MB | | 启动时间 | 约 50ms | 500ms - 2s | | 内存占用 | 空闲时约 10MB | 空闲时约 50MB | | 图表生成 | 内置 Mermaid 解析器 | 基于 AI | | 速率限制 | 自动退避 | 手动设置 | | 缓存机制 | 2 分钟 TTL | 无 | | 熔断机制 | 支持 | 不支持 |

与 Miro 官方 MCP 服务器对比

Miro 已发布 官方 MCP 服务器（测试版）。对比情况如下：

| 特性 | 本服务器 | 官方 Miro MCP 服务器 | |------|------|------| | 工具数量 | 77 种 | 约 5 种（测试版） | | 图表生成 | Mermaid 语法 | 基于 AI | | 批量操作 | 支持 | 不支持 | | 思维导图 | 支持 | 不支持 | | 标签与分组 | 支持 | 不支持 | | 导出功能 | 支持 | 不支持 | | 运行时 | 单 Go 二进制文件 | Node.js | | 速率限制 | 自适应 | 基本限制 | | 缓存机制 | 内置 | 无 | | OAuth 流程 | 内置 CLI | 需要设置 |

何时使用官方服务器：您需要 Miro 支持的工具和 AI 驱动的图表生成功能。

何时使用本服务器：您需要完整的 API 接口、批量操作、思维导图、标签和分组功能，或者希望使用轻量级的二进制文件。

两者可以共存 — 在配置中使用不同的 MCP 服务器名称。

📄 许可证

本项目采用 MIT 许可证。

为 Miro 和 MCP 社区打造。
_{Miro 是 Miro Inc. 的商标。本项目与 Miro 无关联，也未得到其认可。}