Miro MCP服务器
具有OAuth2身份验证的Miro API的模型上下文协议（MCP）服务器。使Claude AI能够以编程方式创建和操纵Miro板。
特性
- 完全支持OAuth2：具有自动令牌刷新功能的授权代码流
- 14 MCP工具 涵盖Miro的所有基本操作：
- 董事会操作（列表、获取、创建） - 项目操作（列表、获取、更新、删除） - 项目创建（便签、形状、文本、框架） - 连接器（创建、更新）
- 速率限制：Miro API速率限制的内置处理
- 错误处理：全面的错误报告和恢复
体系结构模式
独立单帐户MCP服务器：
此服务器遵循 独立模式 在那里它管理自己的Miro OAuth令牌：
- 一个服务器实例=一个Miro帐户（服务器所有者的帐户）
- 本地存储的令牌(
/data/tokens.json在生产中，~/.config/mcps/miro-dev/tokens.json发展中） - 无多用户支持（所有客户端使用相同的Miro帐户）
- 重新身份验证URL:
${BASE_URI}/oauth/authorize（服务器本身）
与mcp网关模式的比较：
这与 mcp-gateway 架构，其中：
- 网关管理令牌 每个用户 跨多个服务
- 每个用户都有自己的服务帐户（Gmail、Miro等）
- 存储在网关数据库中的令牌
- 重新身份验证URL:
${GATEWAY_URL}/mcp/miro/oauth/authorize?user_id=X
在以下情况下选择独立：
- ✅ 所有Claude用户的单个Miro帐户
- ✅ 更简单的部署（无网关基础设施）
- ✅ 直接MCP连接
在以下情况下选择网关：
- ✅ 拥有不同Miro帐户的多个用户
- ✅ 跨服务的统一访问控制
- ✅ 集中式令牌管理
安装
npm install
npm run build配置
1.设置环境变量
复制 .env.example 到 .env 并配置：
cp .env.example .env编辑 .env:
MIRO_CLIENT_ID=your_client_id
MIRO_CLIENT_SECRET=your_client_secret
MIRO_REDIRECT_URI=http://localhost:3000/oauth/callback2.获取OAuth2令牌
提供的令牌已过期。您需要获得新的令牌：
选项A：手动OAuth2流
- 访问授权URL：
https://miro.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/oauth/callback- 授权应用程序并复制
code从重定向URL
- 将代码替换为令牌：
curl -X POST "https://api.miro.com/v1/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=YOUR_CODE_HERE" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "redirect_uri=http://localhost:3000/oauth/callback"- 复制
access_token和refresh_token你的.env文件
选项B：使用现有的OAuth帮助程序（TODO）
将添加一个简单的OAuth回调服务器来自动化此过程。
用法
测试API访问
npm test这将：
- 验证身份验证
- 列出您的董事会
- 创建测试板
- 在测试板上创建项目
启动MCP服务器
npm run dev # Development mode with auto-reload
npm start # Production mode在Claude桌面中配置
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"miro-dev": {
"command": "node",
"args": ["/path/to/miro-mcp/dist/index.js"],
"env": {
"MIRO_CLIENT_ID": "YOUR_CLIENT_ID",
"MIRO_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
"MIRO_ACCESS_TOKEN": "your_access_token",
"MIRO_REFRESH_TOKEN": "your_refresh_token"
}
}
}
}可用工具
董事会运营
list_boards-列出所有可访问的板get_board-获取电路板详细信息create_board-创建新板
项目操作
list_items-列出具有可选类型筛选的项目get_item-获取商品详细信息update_item-更新项目属性delete_item-删除项目
项目创建
create_sticky_note-使用自定义样式创建便签create_shape-创建形状（矩形、圆形等）create_text-创建文本项create_frame-创建用于分组的框架
连接器
create_connector-在项目之间创建线条/箭头update_connector-更新连接器样式
Claude使用示例
Create a Miro board showing 3 agile squads (Alpha, Beta, Gamma).
Each squad has 1 Product Owner, 1 Scrum Master, and 5 developers.
Use frames for each squad, sticky notes for team members, and connectors
to show reporting lines.
Color coding:
- Product Owners: yellow sticky notes
- Scrum Masters: green sticky notes
- Developers: blue sticky notes发展
项目结构
miro-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── oauth.ts # OAuth2 manager
│ ├── miro-client.ts # Miro API client wrapper
│ ├── tools.ts # MCP tool definitions
│ ├── test-api.ts # API testing script
│ └── test-mcp.ts # MCP protocol tests
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── .env # Configuration (not in git)运行测试
npm run build # Build TypeScript
npm test # Test API access
npm run test:integration # Test MCP protocol故障排除
令牌过期错误
如果您看到身份验证错误：
- 访问令牌将在1小时后过期
- 服务器将使用刷新令牌自动刷新
- 如果刷新令牌也过期，则需要重新进行身份验证
自动重新身份验证流程：
当令牌过期或无效时，Claude Desktop/Code将收到一个带有重新身份验证URL的错误：
{
"error": {
"code": -32001,
"message": "Miro authentication expired or invalid.",
"data": {
"authorize_url": "https://your-server.com/oauth/authorize",
"action_hint": "Visit the authorize_url to reauthenticate with Miro"
}
}
}要重新验证，请执行以下操作：
- 访问
authorize_url从错误消息中 - 您将被重定向到Miro进行授权
- 批准后，令牌会自动保存
- 重试您的原始请求
速率限制
Miro允许每个用户每分钟100个请求。客户端跟踪速率限制，如果超过，将报告错误。
连接问题
确保：
- 环境变量设置正确
- 令牌有效且未过期
- 网络允许访问api.miro.com
API文档
许可证
麻省理工学院