Miro MCP Server

什么是 Miro MCP Server？

Miro MCP Server（evalstate 开发的 mcp-miro，以 @llmindset/mcp-miro 发布）是一个社区版 Miro MCP 服务器，让 Claude 等 MCP 客户端通过 Miro REST API 列出白板、读取框架（frame）和元素，并在 Miro 白板上创建便利贴、形状和批量元素。

它是一个小型、本地运行的开源项目，采用 Apache-2.0 许可证。作者特别提到一个出色的用法：拍下实体便利贴的照片，让 Claude 在 Miro 白板上还原它们。Miro 也运营着自己的官方托管 MCP 服务器，详见下文的对比部分。

如何使用 Miro MCP Server？

前置条件：带 npx 的 Node.js、一个 Miro 账号，以及一个针对你要使用的白板所在团队的 Miro OAuth 访问令牌。

获取令牌。在 Miro Developer Portal 中创建应用（或复用已有应用），授予白板读写权限（boards:read、boards:write），然后为你的团队选择 Install app and get OAuth token。服务器从 --token 参数或 MIRO_OAUTH_TOKEN 环境变量读取令牌；两者都设置时以命令行参数为准。

Claude Desktop

打开 claude_desktop_config.json（macOS 位于 ~/Library/Application Support/Claude/，Windows 位于 %APPDATA%/Claude/），添加：

{
  "mcpServers": {
    "mcp-miro": {
      "command": "npx",
      "args": ["-y", "@llmindset/mcp-miro", "--token", "MIRO-OAUTH-KEY"]
    }
  }
}

完成后重启 Claude Desktop。你也可以让 Smithery 自动写入 Claude Desktop 配置：

npx -y @smithery/cli install @llmindset/mcp-miro --client claude

或使用 mcp-get：

npx @michaellatman/mcp-get@latest install @llmindset/mcp-miro

Claude Code

注册同一个包，并通过环境变量传入令牌：

claude mcp add miro -e MIRO_OAUTH_TOKEN=your_token -- npx -y @llmindset/mcp-miro

Cursor 及其他客户端

任何能运行本地 stdio 服务器的客户端，都可以使用上面 JSON 中的 npx -y @llmindset/mcp-miro --token ... 命令。

从源码构建

npm install
npm run build

然后让客户端运行 node /path/to/mcp-miro/build/index.js --token MIRO-OAUTH-KEY。npm run watch 可在代码变更时自动重新构建。

Miro MCP Server 的主要功能

• 列出令牌可访问的所有白板及其 ID
• 将每个白板作为 MCP 资源（miro://board/<id>）公开，内容以 JSON 返回
• 读取白板上的框架，以及某个框架内的元素
• 创建便利贴，可设置文字、位置和 16 种颜色之一（默认黄色）
• 创建带文字的形状，从矩形、圆形到箭头和流程图符号
• 一次调用批量创建最多 20 个不同类型的元素（便利贴、文本、形状、卡片、框架、图片等）
• 内置“Working with MIRO”提示词，说明白板坐标和布局约定
• 通过 --token 或 MIRO_OAUTH_TOKEN 传入令牌，适配任何 stdio MCP 客户端

Miro MCP Server 工具

该服务器提供六个工具：

• 发现与读取：list_boards 返回可用白板及其 ID。get_frames 列出白板上的框架，get_items_in_frame 返回某个框架内的元素。如需读取整个白板，请读取它的 miro://board/<id> 资源。
• 创建内容：create_sticky_note 放置一张带文字、颜色和 x/y 坐标的便利贴。create_shape 添加带文字的形状，可选类型包括 rectangle、circle、star、cloud、right_arrow 和 flow_chart_decision 等。
• 批量操作：bulk_create_items 在单个事务中发送最多 20 个元素。每个元素包含类型（sticky_note、text、shape、card、app_card、frame、image、document 或 embed）以及 data、style、position、geometry 和 parent 设置。

它没有用于更新、移动或删除已有元素的工具，也不能绘制连接线。

Miro MCP Server 的使用场景

• 工作坊数字化：“这是我们回顾会墙面的照片。把每张便利贴都还原到 Team Retro 白板上，按列和颜色分组。”
• 头脑风暴白板：“在白板 X 上用黄色便利贴写下这次讨论中的 15 个功能想法，排成网格。”
• 白板摘要：“读取‘Research findings’框架中的元素，总结主要主题。”
• 快速图表：“画一个简单的流程图，包含一个开始形状、两个处理框和一个判断菱形。”
• 亲和图：粘贴访谈笔记，让 Claude 通过一次 bulk_create_items 调用把它们变成分组的便利贴。

Miro MCP Server 与替代方案对比

• Miro 官方 MCP 服务器：Miro 在 https://mcp.miro.com/ 托管了自己的远程服务器，文档见 developers.miro.com。它使用带动态客户端注册的 OAuth 2.1，你通过 Miro 登录授权，而不必粘贴令牌。Miro 提供了 Claude（网页版和桌面版）、Claude Code、Cursor、VS Code 中的 GitHub Copilot 等客户端的配置说明。在 Enterprise 套餐中，可能需要管理员先启用它。对大多数团队来说，这是功能更完整、有官方支持的选择。
• k-jarzyna/mcp-miro：另一个社区服务器（GitHub，包名 @k-jarzyna/mcp-miro，令牌放在 MIRO_ACCESS_TOKEN 中），覆盖了更多 Miro SDK 功能，包括白板复制/更新/删除、卡片、连接线和元素更新。
• 本服务器适合想要本地进程、普通 OAuth 令牌和一组精简的创建与读取工具的场景。

Miro MCP Server 常见问题排查

• 提示“Miro OAuth token is required”：未找到令牌。在 args 中传入 --token，或在服务器环境中设置 MIRO_OAUTH_TOKEN。
• 出现“Miro API error: 401”或 403：令牌无效、已过期、缺少白板写入权限，或属于与白板不同的团队。为正确的团队重新安装应用并复制新令牌。
• 按 README 中的 JSON 示例无法启动：该示例使用了 arguments 键和本地构建路径。请改用 "args"（如上面的配置），或使用 npx 方式。
• 大型白板只返回部分内容：当前代码在读取白板或框架时每次最多请求 50 个元素，且不会继续翻页。可以按框架分别读取以缩小范围。
• 调试：在项目目录中运行 npm run inspector，在浏览器中打开 MCP Inspector。