# Comprehensive Miro MCP Server
A powerful Model Context Protocol server providing complete access to the Miro REST API v2. This enhanced version offers extensive functionality for board management, content creation, collaboration, and advanced features.
## Features
### 🎯 Complete API Coverage
- **40+ tools** covering all major Miro API endpoints
- Full CRUD operations for all content types
- Advanced board management and collaboration features
- Experimental features like webhooks and advanced search
### 📋 Board Operations
- `list_boards` - List all boards with search and team filtering
- `get_board` - Get detailed board information
- `create_board` - Create new boards with custom settings
- `update_board` - Modify board properties
- `copy_board` - Duplicate existing boards
- `delete_board` - Remove boards permanently
### 🎨 Content Creation
- **Sticky Notes**: 15+ colors, custom positioning, text content
- **Text Items**: Rich formatting, custom fonts and sizes
- **Shapes**: 25+ shapes including flowchart elements
- **Cards**: Title/description cards for structured content
- **Images**: Direct URL embedding with size control
- **Documents**: PDF and document embedding
- **Embeds**: Video and web content embedding
- **Frames**: Container elements for organizing content
- **Connectors**: Link items with optional labels and styling
### 🏷️ Organization Features
- **Tags**: Create, manage, and attach tags to items
- **Groups**: Group multiple items for batch operations
- **Frames**: Organize content in containers
- **Search**: Find items by content and metadata
### 🚀 Advanced Operations
- **Bulk Operations**: Create, update, or delete up to 20 items simultaneously (implemented via sequential API calls)
- **Bulk Connectors**: Create multiple connectors at once to efficiently link items
- **Board Sharing**: Invite users with granular permissions
- **Member Management**: Manage board access and roles
- **Webhooks**: Real-time event notifications (experimental)
### 🎛️ Precise Control
- **Positioning**: Exact pixel placement with configurable origins
- **Styling**: Comprehensive visual customization
- **Geometry**: Control size, rotation, and dimensions
- **Typography**: Font families, sizes, colors, and alignment
## Installation
```bash
npm install @aditya.mishra/miro-mcp
```
## ⚠️ Important API Limitations & Best Practices
Based on extensive testing with the Miro API v2, please note these critical requirements:
### 🎨 Content Creation Requirements
- **Text Items**: Only support `width` in geometry, `height` is NOT supported by Miro API
- **Sticky Notes & Tags**: Must use predefined color names (e.g., "yellow", "red", "blue"), NOT hex codes
- **Connectors**: Both start and end items MUST exist on the board before creating connectors
### 📊 API Limits
- **Bulk Operations**: Maximum 20 items per request (create/update/delete)
- **Board Items**: Minimum limit is 10 when using `get_board_items` with limit parameter
- **Rate Limiting**: Miro API has rate limits - consider delays for large operations
### 🔍 Working with Items
- **Item IDs**: Always obtain item IDs from `get_board_items` or item creation responses
- **Connectors**: Require existing item IDs - use `get_board_items` to find valid item IDs first
- **Tags**: Use predefined color names from the enum lists in tool descriptions
### 📍 Positioning
- **Coordinates**: Use `x`, `y` coordinates for precise placement (pixels from board center)
- **Origins**: Default origin is "center" - items are positioned from their center point
## Authentication
Obtain a Miro OAuth token from your Miro app and provide it via:
### Environment Variable
```bash
export MIRO_OAUTH_TOKEN="your_token_here"
```
### Command Line
```bash
miro-mcp --token "your_token_here"
```
## Usage
### As MCP Server
```json
{
"mcpServers": {
"miro-mcp": {
"command": "npx",
"args": ["@aditya.mishra/miro-mcp"],
"env": {
"MIRO_OAUTH_TOKEN": "your_token_here"
}
}
}
}
```
### Direct Execution
```bash
# List available tools
npx @modelcontextprotocol/inspector build/index.js
# Run with token
MIRO_OAUTH_TOKEN=your_token miro-mcp
```
## Client Configuration
This MCP server works with any Model Context Protocol compatible client. Here are configuration examples for popular clients:
### Claude Desktop
1. **Locate your configuration file:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
2. **Add the Miro MCP server configuration:**
```json
{
"mcpServers": {
"miro-mcp": {
"command": "npx",
"args": ["@aditya.mishra/miro-mcp"],
"env": {
"MIRO_OAUTH_TOKEN": "your_miro_oauth_token_here"
}
}
}
}
```
3. **Restart Claude Desktop** and the Miro tools will be available in your conversations.
### Cursor
1. **Open Cursor Settings** (Cmd/Ctrl + ,)
2. **Search for "MCP"** in settings
3. **Add MCP Server:**
- **Name**: `miro-mcp`
- **Command**: `npx`
- **Args**: `["@aditya.mishra/miro-mcp"]`
- **Environment Variables**: `MIRO_OAUTH_TOKEN=your_token_here`
### Cline (formerly Claude Coder)
Add to your `.clinerc` or MCP configuration:
```json
{
"mcpServers": {
"miro-mcp": {
"command": "npx",
"args": ["@aditya.mishra/miro-mcp"],
"env": {
"MIRO_OAUTH_TOKEN": "your_token_here"
}
}
}
}
```
### Zed Editor
1. **Open Zed Settings** (Cmd/Ctrl + ,)
2. **Add to your `settings.json`:**
```json
{
"experimental.mcp": {
"servers": {
"miro-mcp": {
"command": "npx",
"args": ["@aditya.mishra/miro-mcp"],
"env": {
"MIRO_OAUTH_TOKEN": "your_token_here"
}
}
}
}
}
```
### Continue.dev
Add to your `continue.json` configuration:
```json
{
"mcpServers": [
{
"name": "miro-mcp",
"command": "npx",
"args": ["@aditya.mishra/miro-mcp"],
"env": {
"MIRO_OAUTH_TOKEN": "your_token_here"
}
}
]
}
```
### Generic MCP Client
For any other MCP-compatible client, use these parameters:
- **Command**: `npx`
- **Arguments**: `["@aditya.mishra/miro-mcp"]`
- **Environment**: `MIRO_OAUTH_TOKEN=your_token_here`
- **Working Directory**: Any (the server is self-contained)
## Getting Your Miro OAuth Token
1. **Go to [Miro Developer Portal](https://developers.miro.com/)**
2. **Create a new app** or use an existing one
3. **Get your OAuth token** from the app settings
4. **Set required scopes**: `boards:read`, `boards:write`
5. **Copy the token** and use it in your MCP client configuration
⚠️ **Security Note**: Keep your OAuth token secure and never commit it to version control.
## Tool Categories
### Board Management (6 tools)
- Complete board lifecycle management
- Search and filtering capabilities
- Team-based organization
### Content Creation (9 tools)
- All major content types supported
- Rich styling and positioning options
- URL-based media embedding
### Item Operations (4 tools)
- Universal item management
- Advanced filtering and search
- Batch processing capabilities
### Bulk Operations (4 tools)
- Efficient batch create/update/delete via sequential API calls
- Bulk connector creation for linking multiple items efficiently
- Up to 20 items per operation (validated and enforced)
- Optimized for large-scale changes with proper error handling
### Organization (8 tools)
- Tags for categorization
- Groups for logical clustering
- Frames for spatial organization
- Advanced search capabilities
### Collaboration (2 tools)
- User invitation and management
- Role-based permissions
- Real-time sharing
### Advanced Features (8 tools)
- Webhook management
- Frame-based operations
- Member administration
- Experimental features
## Examples
### Creating a Project Board
```javascript
// 1. Create a new board
await createBoard({
name: "Project Planning",
description: "Q1 project planning board"
});
// 2. Create frames for organization
await createFrame({
boardId: "board_id",
title: "Backlog",
x: 0, y: 0, width: 400, height: 600
});
// 3. Add task cards
await createCard({
boardId: "board_id",
title: "User Authentication",
description: "Implement OAuth2 login flow",
x: 50, y: 50
});
// 4. Connect related items
await createConnector({
boardId: "board_id",
startItemId: "item1",
endItemId: "item2",
caption: "depends on"
});
// 5. Share with team
await shareBoardWithUser({
boardId: "board_id",
email: "team@company.com",
role: "editor"
});
```
### Creating a Mind Map
```javascript
// 1. Central topic
await createStickyNote({
boardId: "board_id",
content: "Main Topic",
color: "yellow",
x: 0, y: 0
});
// 2. Branch topics
const branches = ["Idea 1", "Idea 2", "Idea 3"];
for (let i = 0; i < branches.length; i++) {
const item = await createStickyNote({
boardId: "board_id",
content: branches[i],
color: "light_blue",
x: Math.cos(i * 2 * Math.PI / 3) * 200,
y: Math.sin(i * 2 * Math.PI / 3) * 200
});
await createConnector({
boardId: "board_id",
startItemId: "central_item_id",
endItemId: item.id
});
}
// 3. Add tags for categorization
await createTag({
boardId: "board_id",
title: "Priority High",
fillColor: "#ff0000"
});
```
### Bulk Content Creation
```javascript
// Create multiple items efficiently (up to 20 items)
// Note: Implemented via sequential API calls for reliability
await bulkCreateItems({
boardId: "board_id",
items: [
{
type: "sticky_note",
data: { content: "Task 1" },
style: { fillColor: "yellow" },
position: { x: 0, y: 0 }
},
{
type: "sticky_note",
data: { content: "Task 2" },
style: { fillColor: "pink" },
position: { x: 100, y: 0 }
},
{
type: "shape",
data: { shape: "rectangle", content: "Process" },
position: { x: 200, y: 0 },
geometry: { width: 150, height: 100 }
}
]
});
// Update multiple items at once
await bulkUpdateItems({
boardId: "board_id",
updates: [
{
id: "item_id_1",
data: {
data: { content: "Updated Task 1" },
style: { fillColor: "green" }
}
},
{
id: "item_id_2",
data: {
data: { content: "Updated Task 2" },
style: { fillColor: "blue" }
}
}
]
});
// Delete multiple items at once
await bulkDeleteItems({
boardId: "board_id",
itemIds: ["item_id_1", "item_id_2", "item_id_3"]
});
```
## Available Shapes
### Basic Shapes
- rectangle, round_rectangle, circle, triangle
- rhombus, parallelogram, trapezoid
- pentagon, hexagon, octagon, star
- cloud, cross, can
### Arrows
- right_arrow, left_arrow, left_right_arrow
### Flowchart Elements
- flow_chart_process, flow_chart_decision
- flow_chart_document, flow_chart_terminator
- flow_chart_input_output, flow_chart_delay
- flow_chart_display, flow_chart_preparation
## Color Palette
### Sticky Note Colors
- gray, light_yellow, yellow, orange
- light_green, green, dark_green, cyan
- light_pink, pink, violet, red
- light_blue, blue, dark_blue, black
### Custom Colors
Use any hex color code for shapes, text, and other elements.
## Error Handling
All operations include comprehensive error handling:
- Detailed error messages
- Proper HTTP status codes
- Graceful fallbacks
- Clear debugging information
## Rate Limiting
The server respects Miro's API rate limits:
- Automatic retry logic
- Exponential backoff
- Rate limit headers monitoring
## API Compliance
- Full Miro REST API v2 compatibility
- Consistent data structures
- Standard HTTP methods
- Proper authentication handling
## Development
### Building
```bash
npm run build
```
### Testing
```bash
npm run inspector
```
### Watching
```bash
npm run watch
```
## Limitations
- Maximum 20 items per bulk operation (enforced and validated)
- Bulk operations use sequential API calls (not true bulk endpoints)
- DELETE operations may return empty responses (handled automatically)
- Webhook feature is experimental
- Some advanced enterprise features require appropriate Miro plan
- File uploads not supported (URL-based only)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
MIT License - see LICENSE file for details
## Support
- GitHub Issues for bug reports
- Miro API Documentation: https://miroapp.github.io/api-clients/node/
- MCP Documentation: https://modelcontextprotocol.io/
## Changelog
### v0.2.0 - Comprehensive Enhancement
- Added 35+ new tools covering complete Miro API
- Implemented board management operations
- Added content creation for all item types
- Introduced tags, groups, and organization features
- Added bulk operations for efficiency
- Implemented board sharing and collaboration
- Added webhooks and experimental features
- Enhanced error handling and documentation
### v0.1.1 - Initial Release
- Basic sticky note creation
- Simple board listing
- Frame operations
- Limited shape support
