Miro

Accede a la API REST v2 de Miro para gestionar tableros, crear contenido y colaborar.

Documentación

Servidor MCP Integral de Miro

Un potente servidor de Protocolo de Contexto de Modelo que proporciona acceso completo a la API REST v2 de Miro. Esta versión mejorada ofrece una amplia funcionalidad para la gestión de tableros, creación de contenido, colaboración y funciones avanzadas.

Características

🎯 Cobertura Completa de la API

Más de 40 herramientas que cubren todos los endpoints principales de la API de Miro
Operaciones CRUD completas para todos los tipos de contenido
Gestión avanzada de tableros y funciones de colaboración
Funciones experimentales como webhooks y búsqueda avanzada

📋 Operaciones con Tableros

list_boards - Listar todos los tableros con búsqueda y filtrado por equipo
get_board - Obtener información detallada del tablero
create_board - Crear nuevos tableros con configuraciones personalizadas
update_board - Modificar propiedades del tablero
copy_board - Duplicar tableros existentes
delete_board - Eliminar tableros permanentemente

🎨 Creación de Contenido

Notas adhesivas: Más de 15 colores, posicionamiento personalizado, contenido de texto
Elementos de texto: Formato enriquecido, fuentes y tamaños personalizados
Formas: Más de 25 formas, incluidos elementos de diagramas de flujo
Tarjetas: Tarjetas de título/descripción para contenido estructurado
Imágenes: Inserción directa por URL con control de tamaño
Documentos: Inserción de PDF y documentos
Incrustaciones: Incrustación de videos y contenido web
Marcos: Elementos contenedores para organizar contenido
Conectores: Vincular elementos con etiquetas y estilos opcionales

🏷️ Funciones de Organización

Etiquetas: Crear, gestionar y adjuntar etiquetas a elementos
Grupos: Agrupar múltiples elementos para operaciones por lotes
Marcos: Organizar contenido en contenedores
Búsqueda: Encontrar elementos por contenido y metadatos

🚀 Operaciones Avanzadas

Operaciones por lotes: Crear, actualizar o eliminar hasta 20 elementos simultáneamente (implementado mediante llamadas API secuenciales)
Conectores por lotes: Crear múltiples conectores a la vez para vincular elementos de manera eficiente
Compartir tableros: Invitar usuarios con permisos granulares
Gestión de miembros: Gestionar acceso y roles del tablero
Webhooks: Notificaciones de eventos en tiempo real (experimental)

🎛️ Control Preciso

Posicionamiento: Colocación exacta en píxeles con orígenes configurables
Estilos: Personalización visual integral
Geometría: Controlar tamaño, rotación y dimensiones
Tipografía: Familias de fuentes, tamaños, colores y alineación

Instalación

npm install @aditya.mishra/miro-mcp

⚠️ Limitaciones Importantes de la API y Mejores Prácticas

Basado en pruebas exhaustivas con la API v2 de Miro, tenga en cuenta estos requisitos críticos:

🎨 Requisitos para la Creación de Contenido

Elementos de texto: Solo admiten width en geometría, height NO es compatible con la API de Miro
Notas adhesivas y etiquetas: Deben usar nombres de colores predefinidos (por ejemplo, "amarillo", "rojo", "azul"), NO códigos hexadecimales
Conectores: Tanto el elemento inicial como el final DEBEN existir en el tablero antes de crear conectores

📊 Límites de la API

Operaciones por lotes: Máximo 20 elementos por solicitud (crear/actualizar/eliminar)
Elementos del tablero: El límite mínimo es 10 cuando se usa get_board_items con el parámetro de límite
Limitación de velocidad: La API de Miro tiene límites de velocidad: considere demoras para operaciones grandes

🔍 Trabajo con Elementos

IDs de elementos: Obtenga siempre los IDs de elementos de get_board_items o de las respuestas de creación de elementos
Conectores: Requieren IDs de elementos existentes: use get_board_items para encontrar IDs de elementos válidos primero
Etiquetas: Use nombres de colores predefinidos de las listas de enumeración en las descripciones de herramientas

📍 Posicionamiento

Coordenadas: Use coordenadas x, y para una colocación precisa (píxeles desde el centro del tablero)
Orígenes: El origen predeterminado es "centro": los elementos se posicionan desde su punto central

Autenticación

Obtenga un token OAuth de Miro desde su aplicación de Miro y proporciónelo mediante:

Variable de Entorno

export MIRO_OAUTH_TOKEN="your_token_here"

Línea de Comandos

miro-mcp --token "your_token_here"

Uso

Como Servidor MCP

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

Ejecución Directa

# List available tools
npx @modelcontextprotocol/inspector build/index.js

# Run with token
MIRO_OAUTH_TOKEN=your_token miro-mcp

Configuración del Cliente

Este servidor MCP funciona con cualquier cliente compatible con el Protocolo de Contexto de Modelo. Aquí hay ejemplos de configuración para clientes populares:

Claude Desktop

Localice su archivo de configuración:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Agregue la configuración del servidor MCP de Miro:

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

Reinicie Claude Desktop y las herramientas de Miro estarán disponibles en sus conversaciones.

Cursor

Abra la Configuración de Cursor (Cmd/Ctrl + ,)
Busque "MCP" en la configuración
Agregue el Servidor MCP:
- Nombre: miro-mcp
- Comando: npx
- Argumentos: ["@aditya.mishra/miro-mcp"]
- Variables de Entorno: MIRO_OAUTH_TOKEN=your_token_here

Cline (anteriormente Claude Coder)

Agregue a su .clinerc o configuración de MCP:

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

Editor Zed

Abra la Configuración de Zed (Cmd/Ctrl + ,)
Agregue a su settings.json:

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

Continue.dev

Agregue a su configuración de continue.json:

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

Cliente MCP Genérico

Para cualquier otro cliente compatible con MCP, use estos parámetros:

Comando: npx
Argumentos: ["@aditya.mishra/miro-mcp"]
Entorno: MIRO_OAUTH_TOKEN=your_token_here
Directorio de Trabajo: Cualquiera (el servidor es autónomo)

Obtención de su Token OAuth de Miro

Vaya al Portal de Desarrolladores de Miro
Cree una nueva aplicación o use una existente
Obtenga su token OAuth desde la configuración de la aplicación
Establezca los alcances requeridos: boards:read, boards:write
Copie el token y úselo en la configuración de su cliente MCP

⚠️ Nota de Seguridad: Mantenga su token OAuth seguro y nunca lo envíe al control de versiones.

Categorías de Herramientas

Gestión de Tableros (6 herramientas)

Gestión completa del ciclo de vida del tablero
Capacidades de búsqueda y filtrado
Organización basada en equipos

Creación de Contenido (9 herramientas)

Todos los tipos de contenido principales compatibles
Opciones ricas de estilo y posicionamiento
Inserción de medios basada en URL

Operaciones con Elementos (4 herramientas)

Gestión universal de elementos
Filtrado y búsqueda avanzados
Capacidades de procesamiento por lotes

Operaciones por Lotes (4 herramientas)

Crear/actualizar/eliminar por lotes eficientes mediante llamadas API secuenciales
Creación de conectores por lotes para vincular múltiples elementos de manera eficiente
Hasta 20 elementos por operación (validado y aplicado)
Optimizado para cambios a gran escala con manejo adecuado de errores

Organización (8 herramientas)

Etiquetas para categorización
Grupos para agrupamiento lógico
Marcos para organización espacial
Capacidades de búsqueda avanzada

Colaboración (2 herramientas)

Invitación y gestión de usuarios
Permisos basados en roles
Compartir en tiempo real

Funciones Avanzadas (8 herramientas)

Gestión de webhooks
Operaciones basadas en marcos
Administración de miembros
Funciones experimentales

Ejemplos

Creación de un Tablero de Proyecto

// 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"
});

Creación de un Mapa Mental

// 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"
});

Creación de Contenido por Lotes

// 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"]
});

Formas Disponibles

Formas Básicas

rectángulo, rectángulo_redondeado, círculo, triángulo
rombo, paralelogramo, trapezoide
pentágono, hexágono, octágono, estrella
nube, cruz, lata

Flechas

flecha_derecha, flecha_izquierda, flecha_izquierda_derecha

Elementos de Diagramas de Flujo

proceso_diagrama_flujo, decisión_diagrama_flujo
documento_diagrama_flujo, terminador_diagrama_flujo
entrada_salida_diagrama_flujo, retraso_diagrama_flujo
visualización_diagrama_flujo, preparación_diagrama_flujo

Paleta de Colores

Colores de Notas Adhesivas

gris, amarillo_claro, amarillo, naranja
verde_claro, verde, verde_oscuro, cian
rosa_claro, rosa, violeta, rojo
azul_claro, azul, azul_oscuro, negro

Colores Personalizados

Use cualquier código de color hexadecimal para formas, texto y otros elementos.

Manejo de Errores

Todas las operaciones incluyen un manejo integral de errores:

Mensajes de error detallados
Códigos de estado HTTP adecuados
Alternativas elegantes
Información clara de depuración

Limitación de Velocidad

El servidor respeta los límites de velocidad de la API de Miro:

Lógica de reintento automático
Retroceso exponencial
Monitoreo de encabezados de límite de velocidad

Cumplimiento de la API

Compatibilidad completa con la API REST v2 de Miro
Estructuras de datos consistentes
Métodos HTTP estándar
Manejo adecuado de autenticación

Desarrollo

Compilación

npm run build

Pruebas

npm run inspector

Observación

npm run watch

Limitaciones

Máximo 20 elementos por operación por lotes (aplicado y validado)
Las operaciones por lotes usan llamadas API secuenciales (no endpoints por lotes reales)
Las operaciones DELETE pueden devolver respuestas vacías (manejado automáticamente)
La función de webhook es experimental
Algunas funciones empresariales avanzadas requieren un plan de Miro adecuado
No se admiten cargas de archivos (solo basado en URL)

Contribuciones

Haga un fork del repositorio
Cree una rama de características
Realice sus cambios
Agregue pruebas si corresponde
Envíe una solicitud de extracción

Licencia

Licencia MIT: consulte el archivo LICENSE para obtener detalles

Soporte

Problemas de GitHub para informes de errores
Documentación de la API de Miro: https://miroapp.github.io/api-clients/node/
Documentación de MCP: https://modelcontextprotocol.io/

Registro de Cambios

v0.2.0 - Mejora Integral

Se agregaron más de 35 nuevas herramientas que cubren la API completa de Miro
Se implementaron operaciones de gestión de tableros
Se agregó creación de contenido para todos los tipos de elementos
Se introdujeron etiquetas, grupos y funciones de organización
Se agregaron operaciones por lotes para mayor eficiencia
Se implementaron compartir tableros y colaboración
Se agregaron webhooks y funciones experimentales
Se mejoró el manejo de errores y la documentación

v0.1.1 - Versión Inicial

Creación básica de notas adhesivas
Listado simple de tableros
Operaciones con marcos
Soporte limitado de formas