Miro

Acesse a API REST v2 do Miro para gerenciar quadros, criar conteúdo e colaborar.

Documentação

Servidor Miro MCP Abrangente

Um poderoso servidor Model Context Protocol que fornece acesso completo à API REST v2 do Miro. Esta versão aprimorada oferece funcionalidade extensa para gerenciamento de quadros, criação de conteúdo, colaboração e recursos avançados.

Recursos

🎯 Cobertura Completa da API

Mais de 40 ferramentas cobrindo todos os principais endpoints da API do Miro
Operações CRUD completas para todos os tipos de conteúdo
Gerenciamento avançado de quadros e recursos de colaboração
Recursos experimentais como webhooks e busca avançada

📋 Operações de Quadro

list_boards - Listar todos os quadros com filtros de busca e equipe
get_board - Obter informações detalhadas do quadro
create_board - Criar novos quadros com configurações personalizadas
update_board - Modificar propriedades do quadro
copy_board - Duplicar quadros existentes
delete_board - Remover quadros permanentemente

🎨 Criação de Conteúdo

Notas adesivas: Mais de 15 cores, posicionamento personalizado, conteúdo de texto
Itens de texto: Formatação rica, fontes e tamanhos personalizados
Formas: Mais de 25 formas, incluindo elementos de fluxograma
Cartões: Cartões de título/descrição para conteúdo estruturado
Imagens: Incorporação direta por URL com controle de tamanho
Documentos: Incorporação de PDF e documentos
Embeds: Incorporação de vídeo e conteúdo web
Quadros: Elementos contêiner para organizar conteúdo
Conectores: Vincular itens com rótulos e estilos opcionais

🏷️ Recursos de Organização

Tags: Criar, gerenciar e anexar tags a itens
Grupos: Agrupar vários itens para operações em lote
Quadros: Organizar conteúdo em contêineres
Busca: Encontrar itens por conteúdo e metadados

🚀 Operações Avançadas

Operações em lote: Criar, atualizar ou excluir até 20 itens simultaneamente (implementado via chamadas sequenciais à API)
Conectores em lote: Criar vários conectores de uma vez para vincular itens com eficiência
Compartilhamento de quadros: Convidar usuários com permissões granulares
Gerenciamento de membros: Gerenciar acesso e funções do quadro
Webhooks: Notificações de eventos em tempo real (experimental)

🎛️ Controle Preciso

Posicionamento: Posicionamento exato em pixels com origens configuráveis
Estilo: Personalização visual abrangente
Geometria: Controlar tamanho, rotação e dimensões
Tipografia: Famílias de fontes, tamanhos, cores e alinhamento

Instalação

npm install @aditya.mishra/miro-mcp

⚠️ Limitações Importantes da API e Melhores Práticas

Com base em testes extensivos com a API v2 do Miro, observe estes requisitos críticos:

🎨 Requisitos de Criação de Conteúdo

Itens de texto: Suportam apenas width em geometria, height NÃO é suportado pela API do Miro
Notas adesivas e tags: Devem usar nomes de cores predefinidos (ex.: "amarelo", "vermelho", "azul"), NÃO códigos hexadecimais
Conectores: Os itens inicial e final DEVEM existir no quadro antes de criar conectores

📊 Limites da API

Operações em lote: Máximo de 20 itens por solicitação (criar/atualizar/excluir)
Itens do quadro: O limite mínimo é 10 ao usar get_board_items com parâmetro de limite
Limitação de taxa: A API do Miro tem limites de taxa - considere atrasos para operações grandes

🔍 Trabalhando com Itens

IDs de itens: Sempre obtenha IDs de itens de get_board_items ou respostas de criação de itens
Conectores: Exigem IDs de itens existentes - use get_board_items para encontrar IDs de itens válidos primeiro
Tags: Use nomes de cores predefinidos das listas de enumeração nas descrições das ferramentas

📍 Posicionamento

Coordenadas: Use coordenadas x, y para posicionamento preciso (pixels a partir do centro do quadro)
Origens: A origem padrão é "centro" - os itens são posicionados a partir do ponto central

Autenticação

Obtenha um token OAuth do Miro no seu aplicativo Miro e forneça-o via:

Variável de Ambiente

export MIRO_OAUTH_TOKEN="your_token_here"

Linha de Comando

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

Execução Direta

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

# Run with token
MIRO_OAUTH_TOKEN=your_token miro-mcp

Configuração do Cliente

Este servidor MCP funciona com qualquer cliente compatível com Model Context Protocol. Aqui estão exemplos de configuração para clientes populares:

Claude Desktop

Localize seu arquivo de configuração:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Adicione a configuração do servidor Miro MCP:

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

Reinicie o Claude Desktop e as ferramentas do Miro estarão disponíveis em suas conversas.

Cursor

Abra as Configurações do Cursor (Cmd/Ctrl + ,)
Pesquise por "MCP" nas configurações
Adicione o Servidor MCP:
- Nome: miro-mcp
- Comando: npx
- Argumentos: ["@aditya.mishra/miro-mcp"]
- Variáveis de Ambiente: MIRO_OAUTH_TOKEN=your_token_here

Cline (anteriormente Claude Coder)

Adicione ao seu .clinerc ou configuração MCP:

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

Editor Zed

Abra as Configurações do Zed (Cmd/Ctrl + ,)
Adicione ao seu settings.json:

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

Continue.dev

Adicione à sua configuração 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 qualquer outro cliente compatível com MCP, use estes parâmetros:

Comando: npx
Argumentos: ["@aditya.mishra/miro-mcp"]
Ambiente: MIRO_OAUTH_TOKEN=your_token_here
Diretório de Trabalho: Qualquer (o servidor é autossuficiente)

Obtendo Seu Token OAuth do Miro

Acesse o Portal do Desenvolvedor Miro
Crie um novo aplicativo ou use um existente
Obtenha seu token OAuth nas configurações do aplicativo
Defina os escopos necessários: boards:read, boards:write
Copie o token e use-o na configuração do seu cliente MCP

⚠️ Nota de Segurança: Mantenha seu token OAuth seguro e nunca o envie para controle de versão.

Categorias de Ferramentas

Gerenciamento de Quadros (6 ferramentas)

Gerenciamento completo do ciclo de vida do quadro
Recursos de busca e filtragem
Organização baseada em equipe

Criação de Conteúdo (9 ferramentas)

Todos os principais tipos de conteúdo suportados
Opções ricas de estilo e posicionamento
Incorporação de mídia baseada em URL

Operações de Itens (4 ferramentas)

Gerenciamento universal de itens
Filtragem e busca avançadas
Recursos de processamento em lote

Operações em Lote (4 ferramentas)

Criar/atualizar/excluir em lote eficiente via chamadas sequenciais à API
Criação de conectores em lote para vincular vários itens com eficiência
Até 20 itens por operação (validado e aplicado)
Otimizado para mudanças em grande escala com tratamento adequado de erros

Organização (8 ferramentas)

Tags para categorização
Grupos para agrupamento lógico
Quadros para organização espacial
Recursos avançados de busca

Colaboração (2 ferramentas)

Convite e gerenciamento de usuários
Permissões baseadas em funções
Compartilhamento em tempo real

Recursos Avançados (8 ferramentas)

Gerenciamento de webhooks
Operações baseadas em quadros
Administração de membros
Recursos experimentais

Exemplos

Criando um Quadro de Projeto

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

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

Criação de Conteúdo em Lote

// 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 Disponíveis

Formas Básicas

retângulo, retângulo_arredondado, círculo, triângulo
losango, paralelogramo, trapézio
pentágono, hexágono, octógono, estrela
nuvem, cruz, lata

Setas

seta_direita, seta_esquerda, seta_esquerda_direita

Elementos de Fluxograma

fluxograma_processo, fluxograma_decisão
fluxograma_documento, fluxograma_terminador
fluxograma_entrada_saída, fluxograma_atraso
fluxograma_exibição, fluxograma_preparação

Paleta de Cores

Cores de Notas Adesivas

cinza, amarelo_claro, amarelo, laranja
verde_claro, verde, verde_escuro, ciano
rosa_claro, rosa, violeta, vermelho
azul_claro, azul, azul_escuro, preto

Cores Personalizadas

Use qualquer código de cor hexadecimal para formas, texto e outros elementos.

Tratamento de Erros

Todas as operações incluem tratamento abrangente de erros:

Mensagens de erro detalhadas
Códigos de status HTTP adequados
Fallbacks graciosos
Informações claras de depuração

Limitação de Taxa

O servidor respeita os limites de taxa da API do Miro:

Lógica automática de nova tentativa
Backoff exponencial
Monitoramento de cabeçalhos de limite de taxa

Conformidade com a API

Compatibilidade total com a API REST v2 do Miro
Estruturas de dados consistentes
Métodos HTTP padrão
Tratamento adequado de autenticação

Desenvolvimento

Compilação

npm run build

Testes

npm run inspector

Observação

npm run watch

Limitações

Máximo de 20 itens por operação em lote (aplicado e validado)
Operações em lote usam chamadas sequenciais à API (não endpoints verdadeiros de lote)
Operações DELETE podem retornar respostas vazias (tratadas automaticamente)
O recurso de webhook é experimental
Alguns recursos avançados empresariais exigem plano Miro adequado
Uploads de arquivos não suportados (somente baseado em URL)

Contribuindo

Faça um fork do repositório
Crie um branch de recurso
Faça suas alterações
Adicione testes, se aplicável
Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes

Suporte

GitHub Issues para relatórios de bugs
Documentação da API do Miro: https://miroapp.github.io/api-clients/node/
Documentação do MCP: https://modelcontextprotocol.io/

Changelog

v0.2.0 - Aprimoramento Abrangente

Adicionadas mais de 35 novas ferramentas cobrindo a API completa do Miro
Implementadas operações de gerenciamento de quadros
Adicionada criação de conteúdo para todos os tipos de itens
Introduzidos tags, grupos e recursos de organização
Adicionadas operações em lote para eficiência
Implementados compartilhamento de quadros e colaboração
Adicionados webhooks e recursos experimentais
Melhorados tratamento de erros e documentação

v0.1.1 - Lançamento Inicial

Criação básica de notas adesivas
Listagem simples de quadros
Operações de quadros
Suporte limitado a formas