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

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

export MIRO_OAUTH_TOKEN="your_token_here"

Command Line

miro-mcp --token "your_token_here"

Usage

As MCP Server

{
  "mcpServers": {
    "miro-mcp": {
      "command": "npx",
      "args": ["@aditya.mishra/miro-mcp"],
      "env": {
        "MIRO_OAUTH_TOKEN": "your_token_here"
      }
    }
  }
}

Direct Execution

# 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:

{
  "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:

{
  "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

{
  "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:

{
  "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

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

// 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

// 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

// 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

npm run build

Testing

npm run inspector

Watching

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