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.

Key Capabilities

Feature	Description
Zero Manual Exports	Point your AI assistant to any Miro board URL; extraction and traversal occur in real time.
Semantic Graph Reduction	Translates raw Miro shapes, sticky notes, cards, and text boxes into structured nodes and edges.
Short-ID Context Compression	Assigns compact IDs (`n1`, `n2`, `n3`) to minimize token consumption in LLM context windows.
In-Memory TTL Caching	Prevents redundant Miro API requests during multi-turn developer chat conversations.
Dual Transport Support	Operates over standard input/output (`stdio`) for local development or `streamable-http` for remote container deployments.
Multi-Editor Ready	Native configurations for Google Antigravity, Cursor, and Anthropic Claude Code.

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

File	Purpose
`items.json`	Complete raw JSON array of all items on the board.
`connectors.json`	Complete raw JSON array of all board connectors and captions.
`architecture_graph.json`	Compressed semantic graph featuring shortened IDs (`n1`, `n2`...).
`architecture.md`	Ultra-compact Markdown representation tailored for LLM prompt context.
`id_map.json`	Bi-directional mapping between raw Miro IDs and compressed short IDs.
`relationships.json`	Human-readable component relationship inventory.
`board.json`	Consolidated snapshot containing all items, connectors, and relations.

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

Variable	Required	Default	Description
`MIRO_ACCESS_TOKEN`	Yes (or `MIRO_API_KEY`)	—	Miro API Personal Access Token.
`MIRO_BOARD_ID`	Only for `main.py`	—	Target Miro board identifier for standalone runs.
`MCP_TRANSPORT`	No	`stdio`	Transport protocol: `stdio` (local) or `http` (remote).
`PORT`	No	`8000`	HTTP listen port when `MCP_TRANSPORT=http`.
`MIRO_OUTPUT_DIR`	No	`miro_data`	Directory for files generated by `main.py`.

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

Error Code	HTTP Status	Meaning	Resolution
`MIRO_AUTH_TOKEN_MISSING`	—	No access token was provided in header or env.	Add `MIRO_ACCESS_TOKEN` to env or `Authorization: Bearer <token>` in header.
`MIRO_AUTHENTICATION_FAILED`	`401`	Token is invalid, revoked, or expired.	Generate a new token in Miro Developer settings.
`MIRO_BOARD_ACCESS_DENIED`	`403`	Token lacks permission for this specific board.	Confirm board is shared with the Miro account owning the token.
`MIRO_BOARD_NOT_FOUND`	`404`	Board URL does not exist or was deleted.	Check board URL spelling and verify board exists.
`MIRO_RATE_LIMITED`	`429`	Miro rate limit threshold reached.	Server respects `Retry-After`; wait and retry.
`INVALID_MIRO_URL`	—	Provided string is not a valid Miro board link.	Ensure URL begins with `https://miro.com/app/board/`.
`NODE_NOT_FOUND`	—	Requested node ID does not exist in graph.	Call `get_miro_architecture` or `search_miro_architecture` to find IDs.

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.

Navigation Menu

Repository navigation

About

Repository files navigation

Celi Miro MCP

Executive Overview

Key Capabilities

System Architecture & Data Flow

Request Lifecycle Sequence

MCP Tools Reference

1. `get_miro_architecture`

2. `get_miro_board_info`

3. `get_miro_node`

4. `search_miro_architecture`

Installation & Setup

Prerequisites

1. Clone & Install Dependencies

2. Automated 1-Click Client Setup (Windows)

3. Manual Editor Configuration

A. Google Antigravity

B. Cursor IDE

C. Claude Code

Standalone Pipeline Execution (`main.py`)

Generated Artifacts (`miro_data/`)

Sample Markdown Output (`architecture.md`)

Docker & Remote Hosting

Environment Variables Reference

Project Structure

Error Codes & Troubleshooting

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
assets		assets
install		install
mcp_data		mcp_data
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
client.py		client.py
config.py		config.py
graph.py		graph.py
main.py		main.py
mcp_spec.md		mcp_spec.md
parser.py		parser.py
requirements.txt		requirements.txt
storage.py		storage.py

Latest commit

History

Folders and files

Repository files navigation

Celi Miro MCP

Executive Overview

Key Capabilities

System Architecture & Data Flow

Request Lifecycle Sequence

MCP Tools Reference

1. get_miro_architecture

2. get_miro_board_info

3. get_miro_node

4. search_miro_architecture

Installation & Setup

Prerequisites

1. Clone & Install Dependencies

2. Automated 1-Click Client Setup (Windows)

3. Manual Editor Configuration

A. Google Antigravity

B. Cursor IDE

C. Claude Code

Standalone Pipeline Execution (main.py)

Generated Artifacts (miro_data/)

Sample Markdown Output (architecture.md)

Docker & Remote Hosting

Environment Variables Reference

Project Structure

Error Codes & Troubleshooting

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. `get_miro_architecture`

2. `get_miro_board_info`

3. `get_miro_node`

4. `search_miro_architecture`

Standalone Pipeline Execution (`main.py`)

Generated Artifacts (`miro_data/`)

Sample Markdown Output (`architecture.md`)