wrsmith108/miro-mcp

🎯 Miro MCP - Galaxy Product Discovery Board

Status: ✅ Implementation Complete | Framework: Teresa Torres Continuous Discovery | Last Updated: January 20, 2025

🚀 Project Overview

A Model Context Protocol (MCP) server for Miro that programmatically implements Teresa Torres' Continuous Discovery methodology. Successfully created a comprehensive product discovery framework across 4 major frames with 400+ sticky notes, zero overlaps, and clear visual hierarchy.

Product Outcome Focus: "Users achieve first meaningful insight within 15 minutes"

✨ What We Built

4 Complete Frames

1. OST2 (Opportunity Solution Tree) - Hierarchical discovery structure
2. Galaxy Assess & Prioritize - Impact/Effort matrix and prioritization
3. Galaxy Solution Story Mapping - User journey with 53 stories
4. Galaxy Testing Assumptions - 16 assumptions across 5 categories

Key Achievements

• 🎯 400+ sticky notes with perfect layout (no overlaps)
• 📊 16 core assumptions with matched experiments
• 📝 53 user stories across 4 release slices
• 🔬 4-week validation sprint timeline
• 📈 5 success metrics with clear targets

🛠️ Quick Start

# Clone and setup
git clone https://github.com/yourusername/Miro-MCP.git
cd Miro-MCP
npm install

# Configure environment
cp .env.example .env
# Add your MIRO_ACCESS_TOKEN to .env

# Run implementations
node scripts/implementations/ost2-implementation.js
node scripts/implementations/assess-prioritize-implementation.js
node scripts/implementations/solution-story-mapping.js
node scripts/implementations/testing-assumptions-implementation.js

📁 Project Structure

Miro-MCP/
├── scripts/
│   ├── implementations/     # Main board creation scripts
│   │   ├── ost2-implementation.js
│   │   ├── assess-prioritize-implementation.js
│   │   ├── solution-story-mapping.js
│   │   └── testing-assumptions-implementation.js
│   └── utilities/           # Helper scripts and tools
│       ├── layout-designer.js      # Prevents overlaps
│       ├── delete-misplaced-stickies.js
│       └── fix-story-mapping.js
├── documentation/
│   ├── RETROSPECTIVE.md    # Detailed lessons learned
│   ├── PROJECT_SUMMARY.md  # Executive summary
│   └── README.md           # This file
└── configuration/
    ├── .env                # API credentials
    └── package.json        # Dependencies

🎨 Visual Design System

Color Coding

• 🔴 Red: Critical risks/assumptions
• 🟠 Orange: High priority items
• 🟡 Yellow: Medium priority
• 🟢 Green: Validated/Low risk
• 🔵 Blue: Experiments/Actions
• 🟣 Violet: Metrics
• 🔷 Dark Blue: Headers/Categories

Layout Standards

• 550px horizontal spacing between columns
• 200px vertical spacing between rows
• 320x140px standard sticky note size
• Zero overlaps using Layout Designer module

💡 Key Technical Insights

Miro API Best Practices

// Use generic endpoints when specific ones fail
await miroApi.delete(`/boards/${BOARD_ID}/items/${itemId}`); // ✅ Works
// Not: await miroApi.delete(`/boards/${BOARD_ID}/sticky_notes/${itemId}`); // ❌ May fail

// Essential rate limiting
await sleep(150); // Minimum safe delay between API calls

// Frame positioning is relative to center
const frameCenter = { x: frame.position.x, y: frame.position.y };

Layout Designer Pattern

const layoutDesigner = new LayoutDesigner({
  minPadding: 80,
  horizontalGap: 550,    // Wide spacing prevents overlaps
  verticalGap: 200,       // Generous vertical gaps
  useGrid: true,
  gridCellWidth: 350,
  gridCellHeight: 180
});

📊 Implementation Results

🚀 Next Steps

Immediate Actions

• Review frames with stakeholders
• Export PDF documentation
• Share board with team
• Begin Week 1 experiments

Short-term Improvements

• Add interactive elements (tags, links)
• Create reusable templates
• Implement health checks
• Add navigation guide

Long-term Enhancements

• Board versioning system
• Analytics integration
• Project management sync
• Automated updates

🔧 Development

With Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "miro": {
      "command": "node",
      "args": ["./dist/server.js"],
      "env": {
        "MIRO_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

Commands

npm run dev      # Development mode
npm run build    # Build TypeScript
npm test         # Run tests
npm run inspect  # MCP Inspector

📚 Documentation

• - Detailed lessons learned
• - Executive summary
• - Claude Code guidelines

🏆 Key Learnings

1. Teresa Torres Framework works exceptionally well for structured discovery
2. Layout Designer Module essential for professional appearance
3. State Persistence critical for recovery from failures
4. Wide Spacing (550px+) prevents all overlap issues
5. Generic API Endpoints more reliable than specific ones

🙏 Acknowledgments

• Teresa Torres - Continuous Discovery Habits methodology
• Miro - Comprehensive API and platform
• Anthropic - Claude and MCP SDK
• Community - Testing and feedback

📄 License

MIT License - See LICENSE file

📞 Support

• Issues: Submit via GitHub Issues
• Board: View at https://miro.com/app/board/uXjVJS1vI0k=/
• Status: Production Ready ✅

Version: 1.0.0 Completed: January 20, 2025 Total Duration: ~4 hours Result: Complete success with all objectives achieved 🎉