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

✨ 主要特性

可执行操作

语音操作示例

• "添加一个黄色便签，内容为 '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）、形状（[] 矩形、{} 菱形、(()) 圆形）、带标签的边。

📚 详细文档

🔧 技术细节

77 种工具详情

性能优化

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

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

HTTP 模式端点

当使用 -http :8080 运行时：

健康检查响应示例：

{
  "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。

支持的平台

支持的 AI 工具

配置指南请参考 SETUP.md。

账户兼容性

与其他方案对比

与 TypeScript 替代方案对比

与 Miro 官方 MCP 服务器对比

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

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

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

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

📄 许可证

本项目采用 MIT 许可证。

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