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 無關聯，也未得到其認可。}