Miro MCP Skill

Miro MCP服务器

版本：0.1.0

模型上下文协议（MCP）服务器，使Claude和Claude Code能够在Miro板上执行CRUD操作。

概述

此MCP服务器为Claude提供了以下能力：

• 阅读 米罗板具有全面的空间和结构理解
• 创建 具有精确坐标控制的项目（便签、形状、文本）
• 更新 现有项目
• 删除 物品
• 分析 董事会结构、关系和空间组织

主要设计目标： 使Claude Code能够通过精确的坐标控制以编程方式创建美观、组织良好的Miro图。

特性

第1阶段（当前）

• ✅ OAuth 2.0身份验证与令牌管理
• ✅ 阅读带有完整几何细节的电路板
• ✅ 在精确坐标处创建便签
• ✅ 在精确坐标处创建形状（矩形、圆形等）
• ✅ 在项目之间创建连接器
• ✅ 查询板边界和项目几何形状

第二阶段（计划中）

• 更新项目内容、位置和样式
• 删除项目
• 批量操作
• 框架支架
• 高级空间分析

第三阶段（未来）

• 常见模式的模板系统
• 智能布局建议
• 内容提取和分析

建筑

协调战略

此服务器针对以下方面进行了优化 精确坐标控制 为了实现美学图表的创建：

• 所有创建操作都接受显式 x, y 坐标
• Claude Code以编程方式计算布局
• 辅助工具提供坐标计算（网格、径向等）
• 可用于空间推理的完整几何信息

关键组件

miro-mcp/
├── miro_mcp/
│   ├── server.py          # FastMCP server with tool definitions
│   ├── auth.py            # OAuth 2.0 flow and token management
│   ├── client.py          # Miro API client with rate limiting
│   ├── models.py          # Pydantic data models
│   ├── analyzer.py        # Spatial analysis and clustering
│   └── config.py          # Configuration management
├── tests/
│   ├── test_auth.py
│   ├── test_client.py
│   └── test_tools.py
├── docs/
│   ├── ARCHITECTURE.md    # Detailed architecture documentation
│   ├── API.md            # Miro API integration details
│   └── USAGE.md          # Usage examples and patterns
├── pyproject.toml
└── README.md

安装

先决条件

• Python 3.10或更高版本
• 具有开发人员访问权限的Miro帐户
• 克劳德桌面或克劳德代码

1.克隆存储库

git clone https://github.com/yourusername/miro-mcp.git
cd miro-mcp

2.安装依赖项

pip install -e .

3.配置Miro OAuth应用程序

1. 首选 Miro开发者门户
2. 创建新应用程序
3. 配置OAuth设置：

- 重定向URI: http://localhost:8000/callback - 范围: boards:read, boards:write

1. 复制客户端ID和客户端密码

4.设置环境变量

export MIRO_CLIENT_ID="your_client_id"
export MIRO_CLIENT_SECRET="your_client_secret"
export MIRO_REDIRECT_URI="http://localhost:8000/callback"

或者创建一个 .env 文件：

MIRO_CLIENT_ID=your_client_id
MIRO_CLIENT_SECRET=your_client_secret
MIRO_REDIRECT_URI=http://localhost:8000/callback

5.运行初始OAuth安装程序

python -m miro_mcp.auth setup

这将：

• 启动本地OAuth回调服务器
• 打开浏览器进行授权
• 安全地保存令牌

6.配置MCP服务器

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "miro": {
      "command": "python",
      "args": ["-m", "miro_mcp.server"],
      "env": {
        "MIRO_CLIENT_ID": "your_client_id",
        "MIRO_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

快速开始

示例1：阅读公告板

# Ask Claude Code:
# "Read the board at https://miro.com/app/board/uXjVKB..."

board = await miro_read_board("uXjVKB...")
print(f"Board has {len(board.items)} items")
print(f"Bounds: {board.bounds.width} x {board.bounds.height}")

示例2：创建一个简单的图表

# "Create a 3-step process flow diagram"

# Get board bounds to find empty space
board = await miro_read_board(board_id)
start_x = board.bounds.max_x + 500
start_y = board.bounds.center_y

# Create shapes with precise spacing
steps = ["Plan", "Execute", "Review"]
shape_ids = []

for i, step in enumerate(steps):
    x = start_x + i * 400
    shape = await miro_create_shape(
        board_id=board_id,
        shape_type="rectangle",
        content=step,
        x=x,
        y=start_y,
        width=300,
        height=150,
        color="light_blue"
    )
    shape_ids.append(shape.id)

# Connect them
for i in range(len(shape_ids) - 1):
    await miro_create_connector(
        board_id=board_id,
        start_item_id=shape_ids[i],
        end_item_id=shape_ids[i+1],
        start_position="right",
        end_position="left"
    )

示例3：分析现有板

# "What are the main themes on this brainstorm board?"

board = await miro_read_board(board_id)

# Extract all sticky note content
notes = [item.content for item in board.items if item.type == "sticky_note"]

# Claude analyzes the text content
# Can identify clusters, themes, patterns

可用工具

读取操作

miro_list_boards

列出经过身份验证的用户可访问的所有板。

miro_read_board

阅读包含完整几何细节的完整电路板内容。

退货：

• 所有项目（便签、形状、文本、框架）
• 具有开始/结束关系的连接器
• 完整的位置和尺寸数据
• 董事会界限

miro_get_board_bounds

获取板上所有内容的边界框。

miro_get_item_geometry

获取特定物品的精确位置和尺寸。

创建操作

miro_create_sticky_note

在精确坐标处创建便签。

参数：

• board_id：目标板ID
• content：文本内容
• x, y：坐标（必填）
• width, height：尺寸（可选）
• color：备注颜色（可选）

miro_create_shape

在精确坐标处创建形状（矩形、圆形、三角形等）。

参数：

• board_id：目标板ID
• shape_type：矩形、圆形、三角形、菱形等。
• content：形状内的可选文本
• x, y：坐标（必填）
• width, height：尺寸（可选）
• color：形状颜色（可选）

miro_create_connector

在两个项目之间创建连接线。

参数：

• board_id：目标板ID
• start_item_id：源项ID
• end_item_id：目标项目ID
• start_position：从哪个边连接（顶部/底部/左侧/右侧/自动）
• end_position：连接到哪个边缘（顶部/底部/左侧/右侧/自动）

布局辅助工具

miro_calculate_grid_positions

计算网格布局的位置。

miro_calculate_circle_positions

计算径向/圆形布局的位置。

使用模式

模式1：创建前理解

# 1. Read existing board
board = await miro_read_board(board_id)

# 2. Analyze spatial organization
# - Where is content?
# - What spacing is used?
# - What colors/styles are present?

# 3. Place new content in harmony with existing
new_x = board.bounds.max_x + 500  # To the right

模式2：程序化布局

# Calculate all positions first
positions = []
for i, item in enumerate(items):
    row = i // 5
    col = i % 5
    x = base_x + col * 300
    y = base_y + row * 300
    positions.append((x, y))

# Then create all items
for (x, y), content in zip(positions, items):
    await miro_create_sticky_note(board_id, content, x, y)

模式3：结构化图

# Create hierarchical org chart
root_x, root_y = 1000, 500
spacing_x = 400
spacing_y = 300

# Top level
ceo = await miro_create_shape(board_id, "rectangle", "CEO", root_x, root_y)

# Second level
for i, dept in enumerate(["Engineering", "Sales", "Marketing"]):
    x = root_x - spacing_x + i * spacing_x
    y = root_y + spacing_y
    dept_shape = await miro_create_shape(board_id, "rectangle", dept, x, y)
    await miro_create_connector(board_id, ceo.id, dept_shape.id)

发展

运行测试

pytest tests/

类型检查

mypy miro_mcp/

代码格式化

black miro_mcp/
ruff check miro_mcp/

故障排除

身份验证问题

• 验证客户端ID和客户端密码是否正确
• 检查重定向URI是否完全匹配（包括端口）
• 确保启用了所需的作用域
• 尝试重新运行 python -m miro_mcp.auth setup

速率限制

• 服务器实现自动速率限制（100要求/分钟）
• 429个错误的指数回退
• 尽可能考虑批处理操作

协调问题

• 米罗使用任意坐标空间（可以是负数，非常大）
• 始终查询 miro_get_board_bounds 了解规模
• 先用小偏移进行测试，以验证位置

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

资源

• Miro REST API文档
• 模型上下文协议
• FastMCP文档

路线图

第1阶段（v0.1.0）-电流

• \[x\] OAuth身份验证
• \[x\] 基本读取操作
• \[x\] 创建便签和形状
• \[x\] 连接器支架
• \[\]全面的错误处理
• \[\]测试覆盖率

第2阶段（v0.2.0）

• \[\]更新操作
• \[\]删除操作
• \[\]框架支撑
• \[\]批量操作
• \[\]高级空间分析

第3阶段（v0.3.0）

• \[\]模板系统
• \[\]模式识别
• \[\]内容提取
• \[\]图像支持

支持

对于问题、疑问或贡献：

• GitHub问题：\[GitHub.com/yourusername/miro mcp/Issues\]
• 文档：\[docs/\]

更新日志

0.1.0 (2026-02-13)

添加

• 项目说明和开发指南（.claude/claude.md）
• 规范驱动的开发基础架构（规范/目录）
• 测试约定（无模拟，真实实现）
• 基于坐标的设计策略文档