Celi Miro MCP

Model Context Protocol (MCP) server for converting live Miro architecture diagrams into semantic, AI-ready graph context for coding assistants.

Executive Overview

Celi Miro MCP enables modern AI coding agents—including Antigravity, Claude Code, and Cursor—to deeply inspect, traverse, and understand architectural diagrams created on Miro whiteboards.

Instead of manually exporting diagrams, screenshotting boards, or manually describing system architectures, you can paste any Miro board URL directly into your AI chat:

"Inspect the architecture in this board and implement the missing authentication service:
 https://miro.com/app/board/uXjVHCjkewI=/"

Your AI assistant automatically queries the Celi Miro MCP server, fetches board items and connectors, parses semantic groupings and relationships, compresses the topology into an optimal context graph, and applies the architecture directly to your codebase.

Related MCP server: Excalidraw Architect MCP

Key Capabilities

System Architecture & Data Flow

The pipeline transforms raw whiteboard visual primitives into topological system architectures through four discrete phases:

[ Miro Board URL ] 
       │
       ▼
 1. URL Parser & Guard ─────── Validates board URL syntax & token presence
       │
       ▼
 2. Miro REST Client   ─────── Paginates /v2/boards/{board_id}/items & /connectors
       │
       ▼
 3. Graph Engine       ─────── Filters shapes, cleans HTML, resolves labels & groups
       │
       ▼
 4. Semantic Reducer   ─────── Builds adjacency graph, generates short-ID map (n1, n2...)
       │
       ▼
[ FastMCP Server ]     ─────── Delivers context to Antigravity, Claude Code, or Cursor

Request Lifecycle Sequence

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant Agent as AI Coding Agent (Antigravity / Cursor)
    participant MCP as Celi Miro MCP Server
    participant Miro as Miro REST API v2

    Dev->>Agent: "Analyze architecture: https://miro.com/app/board/uXjV.../"
    Agent->>MCP: get_miro_architecture(board_url)
    MCP->>MCP: Parse board ID & verify auth header
    MCP->>Miro: GET /v2/boards/{board_id}/items (paginated)
    Miro-->>MCP: Raw items (shapes, cards, text)
    MCP->>Miro: GET /v2/boards/{board_id}/connectors (paginated)
    Miro-->>MCP: Raw connectors & captions
    MCP->>MCP: Strip HTML, resolve node labels & group hierarchy
    MCP->>MCP: Build adjacency list & compress to compact graph
    MCP-->>Agent: JSON semantic architecture graph + token map
    Agent->>Dev: Delivers precise architectural insights & code scaffolding

MCP Tools Reference

The server exposes four focused MCP tools designed for agentic reasoning:

1. get_miro_architecture

Extracts the complete semantic architecture graph for a given Miro board.

• Parameters:

  • board_url (string, required): Full Miro board URL (e.g., https://miro.com/app/board/uXjVHCjkewI=/).

  • force_refresh (boolean, optional, default: false): Bypass TTL cache and re-fetch directly from Miro.

• Example Agent Query:

  "What are all the services and databases defined on this architecture board?"

• Response Format:

  {
    "success": true,
    "board_id": "uXjVHCjkewI=",
    "nodes": [
      { "id": "n1", "label": "API Gateway", "type": "shape", "fill": "#2d9cdb" },
      { "id": "n2", "label": "Authentication Service", "type": "shape", "fill": "#27ae60" },
      { "id": "n3", "label": "User Database", "type": "shape", "fill": "#f2994a" }
    ],
    "edges": [
      { "source": "n1", "target": "n2", "directed": true, "label": "POST /auth/login" },
      { "source": "n2", "target": "n3", "directed": true, "label": "SQL Query" }
    ],
    "id_map": {
      "3458764512345678901": "n1",
      "3458764512345678902": "n2",
      "3458764512345678903": "n3"
    }
  }

2. get_miro_board_info

Lightweight pre-flight probe to verify token permissions and board accessibility without downloading the complete canvas.

• Parameters:

  • board_url (string, required): Full Miro board URL.

• Example Agent Query:

  "Can I access this Miro board with my current credentials?"

• Response Format:

  {
    "success": true,
    "board_id": "uXjVHCjkewI=",
    "accessible": true
  }

3. get_miro_node

Retrieves a specific component by its compressed node ID along with all immediate upstream and downstream connections.

• Parameters:

  • board_url (string, required): Full Miro board URL.

  • node_id (string, required): Compressed node ID (e.g., "n2").

  • force_refresh (boolean, optional, default: false): Force cache invalidation.

• Example Agent Query:

  "Inspect node n2: what services depend on it and what does it connect to?"

• Response Format:

  {
    "success": true,
    "node": {
      "id": "n2",
      "label": "Authentication Service",
      "type": "shape"
    },
    "connections": [
      {
        "id": "n1",
        "label": "API Gateway",
        "direction": "incoming",
        "edge_label": "POST /auth/login"
      },
      {
        "id": "n3",
        "label": "User Database",
        "direction": "outgoing",
        "edge_label": "SQL Query"
      }
    ]
  }

4. search_miro_architecture

Performs a case-insensitive search across all node labels on the board to locate specific components.

• Parameters:

  • board_url (string, required): Full Miro board URL.

  • query (string, required): Search term (e.g., "database", "redis", "payment").

  • force_refresh (boolean, optional, default: false): Force cache invalidation.

• Example Agent Query:

  "Search the board for any components related to 'payment' or 'checkout'."

• Response Format:

  {
    "success": true,
    "query": "payment",
    "matches": [
      { "id": "n7", "label": "Payment Processing Service", "type": "card" },
      { "id": "n8", "label": "Stripe Webhook Handler", "type": "shape" }
    ]
  }

Installation & Setup

Prerequisites

• Python 3.10 or later

• A Miro account with a Personal Access Token (Generate Miro Token)

1. Clone & Install Dependencies

# Clone the repository
git clone <repo-url>
cd "miro MCP/project"

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install required dependencies
pip install -r requirements.txt

2. Automated 1-Click Client Setup (Windows)

Use the built-in interactive setup script to configure your AI editors in seconds:

# Run the PowerShell setup script
cd install
.\setup_mcp.ps1

Or double-click setup_mcp.bat. The installer will prompt for your Miro Access Token and automatically configure:

• Google Antigravity (~/.gemini/config/mcp_config.json)

• Cursor IDE (~/.cursor/mcp.json)

• Claude Code CLI (claude mcp add)

3. Manual Editor Configuration

A. Google Antigravity

Add the server entry to your global or workspace mcp_config.json:

{
  "mcpServers": {
    "celi-miro": {
      "command": "python",
      "args": ["-m", "mcp_data.server"],
      "cwd": "C:/Users/USER/Desktop/miro MCP/project",
      "env": {
        "MIRO_ACCESS_TOKEN": "your_miro_access_token_here",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

For HTTP transport mode:

{
  "mcpServers": {
    "celi-miro": {
      "serverUrl": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer your_miro_access_token_here"
      }
    }
  }
}

B. Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "celi-miro": {
      "command": "python",
      "args": ["-m", "mcp_data.server"],
      "cwd": "C:/Users/USER/Desktop/miro MCP/project",
      "env": {
        "MIRO_ACCESS_TOKEN": "your_miro_access_token_here"
      }
    }
  }
}

C. Claude Code

Run the registration command in your terminal:

# stdio mode
claude mcp add --scope user celi-miro python -m mcp_data.server

# HTTP mode
claude mcp add --transport http --header "Authorization: Bearer YOUR_MIRO_TOKEN" --scope user celi-miro http://127.0.0.1:8000/mcp

Standalone Pipeline Execution (main.py)

You can also run the extraction pipeline as a standalone CLI tool without launching an MCP server:

# Set environment variables in .env
MIRO_ACCESS_TOKEN=your_token_here
MIRO_BOARD_ID=your_board_id_here
MIRO_OUTPUT_DIR=miro_data

# Execute the pipeline
python main.py

Generated Artifacts (miro_data/)

Sample Markdown Output (architecture.md)

# Architecture Graph (uXjVHCjkewI=)

## Items
- n1: API Gateway (shape)
- n2: Authentication Service (shape)
- n3: User Database (shape)
- n4: Redis Session Store (shape)

## Relations
- n1 (API Gateway) -[POST /auth/login]-> n2 (Authentication Service)
- n2 (Authentication Service) -[SQL Query]-> n3 (User Database)
- n2 (Authentication Service) -[Cache Lookup]-> n4 (Redis Session Store)

Docker & Remote Hosting

A production-ready Dockerfile is included for hosting Celi Miro MCP on container platforms (e.g., AWS ECS, Google Cloud Run, Railway):

# Build the Docker container
docker build -t celi-miro-mcp .

# Run with HTTP transport on port 8000
docker run -d \
  -p 8000:8000 \
  -e MCP_TRANSPORT=http \
  -e PORT=8000 \
  -e MIRO_ACCESS_TOKEN=your_token \
  celi-miro-mcp

Test the live endpoint:

curl http://localhost:8000/mcp

Environment Variables Reference

Project Structure

project/
├── assets/                  # AI-generated documentation graphics & diagrams
│   ├── miro_mcp_hero.jpg    # Hero banner illustration
│   ├── mcp_pipeline.jpg     # Technical architecture pipeline schematic
│   └── mcp_tools.jpg        # 4-tool overview and query workflow diagram
├── install/                 # One-click client installer scripts
│   ├── setup_mcp.ps1        # PowerShell automated configuration utility
│   └── setup_mcp.bat        # Windows batch file launcher
├── mcp_data/                # MCP protocol server implementation
│   ├── __init__.py
│   ├── errors.py            # Structured MCP error response builders
│   ├── miro_url.py          # Miro URL validation & board ID extractor
│   ├── pipeline.py          # Cached extraction pipeline with TTL
│   └── server.py            # FastMCP server & tool definitions
├── client.py                # Paginated Miro REST API v2 client
├── config.py                # Environment configuration & constants
├── Dockerfile               # Container build definition (Python 3.12-slim)
├── graph.py                 # Graph construction & short-ID compression
├── LICENSE                  # Non-Commercial Personal & Hobby Use License
├── main.py                  # Standalone local extraction entrypoint
├── parser.py                # HTML tag stripping & node label extraction
├── README.md                # Comprehensive documentation
├── requirements.txt         # Pinned Python package dependencies
└── storage.py               # JSON & Markdown export utilities

Error Codes & Troubleshooting

License

This project is licensed under the Non-Commercial Personal & Hobby Use License.

• Permitted: Personal, educational, experimentation, testing, and hobbyist projects are free of charge.

• Strictly Prohibited: Selling, reselling, sublicensing, leasing, commercial distribution, or incorporating into commercial products/services without explicit prior written authorization from the Copyright Holder.

See LICENSE for the complete legal terms.