Mural MCP Server
Manage and edit Mural boards via MCP: create/read/update/delete board content, navigate workspaces/rooms/murals, and create new murals.
Create and update sticky notes, text boxes, shapes, areas, images, and arrows.
Batch-create up to 1,000 sticky notes, text boxes, or shapes; batch-connect up to 100 widget pairs.
List and get widgets with pagination and type filtering; delete any widget by ID.
Draw connected arrows between widgets or freeform arrows unsnapped to widgets.
List workspaces, rooms, and murals; get mural metadata; create murals in rooms.
Add images from public URLs with auto-detected dimensions, up to 10 MB.
Use OAuth-secured Mural access with optional workspace allowlist and token-efficient stripped responses.
Provides tools to edit Mural board content: create and update sticky notes, text boxes, shapes, areas, images, and connectors; list and retrieve widgets; navigate workspaces, rooms, and murals; and create new murals.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mural MCP Server Create a sticky note saying 'Project kickoff' in my workspace."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mural MCP Server
MCP server for the Mural visual collaboration platform — focused on board content editing: sticky notes, shapes, text boxes, areas, images, and connectors.
Built with the Model Context Protocol SDK and TypeScript. Runs over stdio — compatible with any MCP client (Warp, Cursor, Claude Code, etc.).
Features
20 tools across 4 modules:
Board Editing — Write (13 tools)
Tool | Description |
| Batch-create sticky notes (1–1000) |
| Update text, position, color, size |
| Batch-create text boxes (1–1000) |
| Update a text box |
| Batch-create shapes — rectangle, circle, diamond, triangle, star, hexagon, and 50+ more |
| Update a shape |
| Create grouping areas |
| Update an area |
| Add image from public URL (auto-detects dimensions, max 10 MB) |
| Draw a connected arrow between two widgets |
| Connect multiple widget pairs in one call (up to 100) |
| Draw a freeform arrow (not snapped to widgets) |
| Delete any widget by ID |
Board Editing — Read (2 tools)
Tool | Description |
| List widgets (paginated, default 50, stripped to key fields) |
| Get a single widget by ID |
Navigation (4 tools)
Tool | Description |
| List accessible workspaces |
| List rooms in a workspace (default limit 50) |
| List murals in a room or workspace (default limit 50) |
| Get mural metadata |
Mural Management (1 tool)
Tool | Description |
| Create a new mural (defaults: infinite canvas, grey background) |
Related MCP server: miro-remote-mcp
Token Efficiency
All tool responses are optimized for minimal token usage:
Stripped responses — only decision-relevant fields are returned (id, type, position, text, style essentials)
Compact JSON — no pretty-printing, short keys (
w/h/bginstead ofwidth/height/backgroundColor)Batch summaries — create tools return
{summary, count, ids, preview}instead of full object dumpsPagination —
get_widgetsdefaults to 50 items with cursor-based paginationServer-side validation — shape types validated server-side (no bloated enums in schema)
Prerequisites
1. Register a Mural App
Go to app.mural.co → click your avatar → "Create and manage apps"
Click "New app"
Set the redirect URL to:
http://localhost:9876/callbackNote your Client ID and Client Secret
2. Install & Build
git clone https://github.com/janschmiedgen/mcp-mural.git
cd mcp-mural
npm install
npm run build3. One-Time OAuth Authentication
export MURAL_CLIENT_ID=your_client_id
export MURAL_CLIENT_SECRET=your_client_secret
npm run authThis opens your browser for Mural consent. Tokens are saved to ~/.mural-mcp/tokens.json and auto-refresh at runtime.
MCP Client Setup
Warp
Add as a CLI MCP Server in Settings → MCP Servers:
{
"command": "node",
"args": ["/path/to/mcp-mural/build/index.js"],
"env": {
"MURAL_CLIENT_ID": "your_client_id",
"MURAL_CLIENT_SECRET": "your_client_secret"
}
}Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"mural": {
"command": "node",
"args": ["/path/to/mcp-mural/build/index.js"],
"env": {
"MURAL_CLIENT_ID": "your_client_id",
"MURAL_CLIENT_SECRET": "your_client_secret"
}
}
}
}Claude Code
claude mcp add mural -- node /path/to/mcp-mural/build/index.jsSet MURAL_CLIENT_ID and MURAL_CLIENT_SECRET in your shell environment.
Configuration
Workspace Allowlist (optional)
Restrict access to specific workspaces by setting the MURAL_ALLOWED_WORKSPACES environment variable:
export MURAL_ALLOWED_WORKSPACES="workspace_id_1,workspace_id_2"If not set, all workspaces the authenticated user can access are available.
Development
npm install
npm run build # Compile TypeScript → build/
npm run dev # Run with tsx (hot reload)
npm run auth # Re-authenticate with MuralArchitecture
src/
├── index.ts # Entry point, registers tools, starts stdio transport
├── types.ts # TypeScript interfaces (Widget, Mural, Room, etc.)
├── auth/
│ ├── oauth.ts # OAuth2 + PKCE flow, token refresh
│ ├── token-store.ts # Token persistence (~/.mural-mcp/tokens.json)
│ └── workspace-guard.ts # Workspace allowlist guard
├── client/
│ └── mural-api.ts # HTTP client for Mural Public API v1
├── tools/
│ ├── widgets-write.ts # 13 write tools (create, update, connect, delete)
│ ├── widgets-read.ts # 2 read tools (get_widgets, get_widget)
│ ├── navigation.ts # 4 navigation tools (workspaces, rooms, murals)
│ └── mural-manage.ts # 1 management tool (create_mural)
└── utils/
└── strip.ts # Response strippers for token efficiencyTransport: stdio (no HTTP server at runtime)
Auth: OAuth2 + PKCE, tokens stored in
~/.mural-mcp/tokens.json, auto-refreshAPI: Mural Public API v1 (
https://app.mural.co/api/public/v1)
Mural API Notes
A few quirks discovered during development that may help contributors:
Arrow semantics: In the Mural API,
startRefIdis the widget the arrowhead points TO, andendRefIdis the tail. The arrowhead renders at the first point in the points array.Sticky note styles on creation: Only
fontSizeandtextAligncan be set during creation.backgroundColormust be set via a subsequent update call.Image upload: Requires a 3-step process: (1) download image, (2) create an asset URL via the API, (3) PUT the image to blob storage, (4) create the image widget referencing the asset name.
Vertical arrows:
connect_widgetsmay fail withWIDGET_SIZE_INVALIDwhen source and target are nearly vertically aligned (near-zero arrow width). Usecreate_arrow(freeform) as a fallback.
License
MIT
Available Tools
20 toolsconnect_widgetsC
Draw a connected arrow between two widgets. Provide source/target IDs and positions.
Inputs: muralId (required), sourceX (required), sourceY (required), targetX (required), +7 more.
connect_widgets_batchA
Connect multiple widget pairs with arrows in one call. Returns all arrow IDs.
Inputs: muralId (required), connections (required), style.
create_areaB
Create an area (grouping section) on a mural.
Inputs: x (required), y (required), width (required), height (required), +3 more.
create_arrowA
Draw a freeform arrow (not snapped to widgets). For connected arrows, use connect_widgets.
Inputs: x (required), y (required), width (required), height (required), +3 more.
create_imageA
Add an image to a mural from a public URL. Auto-detects dimensions. Max 10MB.
Inputs: x (required), y (required), url (required), muralId (required), +2 more.
create_muralA
Create a new mural in a room. Returns mural ID + title.
Inputs: roomId (required), title, width, height, +2 more.
create_shapesA
Create shapes on a mural (batch, up to 1000). Common shapes: rectangle, circle, diamond, triangle, star, hexagon. Full list validated server-side.
Inputs: shapes (required), muralId (required).
create_sticky_notesB
Create sticky notes on a mural (batch, up to 1000). Returns IDs.
Inputs: muralId (required), stickies (required).
create_text_boxesA
Create text boxes on a mural (batch, up to 1000). Returns IDs.
Inputs: muralId (required), textBoxes (required).
delete_widgetA
Delete any widget from a mural by ID
Inputs: muralId (required), widgetId (required).
get_muralA
Get metadata for a specific mural (stripped to key fields)
Inputs: muralId (required).
get_widgetA
Get a single widget by ID (stripped to key fields).
Inputs: muralId (required), widgetId (required).
get_widgetsA
List widgets on a mural (stripped to key fields). Default limit 50. Use 'next' cursor to paginate.
Inputs: muralId (required), next, type, limit.
list_muralsA
List murals in a room or workspace (stripped to id+title+roomId). Default limit 50.
Inputs: limit, roomId, workspaceId.
list_roomsA
List rooms in a workspace (stripped to id+name+type). Default limit 50.
Inputs: workspaceId (required), limit.
list_workspacesA
List Mural workspaces (stripped to id+name)
Inputs: no named parameters.
update_areaD
Update an area on a mural
Inputs: muralId (required), widgetId (required), x, y, +4 more.
update_shapeC
Update a shape on a mural
Inputs: muralId (required), widgetId (required), x, y, +4 more.
update_sticky_noteB
Update a sticky note (text, position, color, size)
Inputs: muralId (required), widgetId (required), x, y, +4 more.
update_text_boxC
Update a text box on a mural
Inputs: muralId (required), widgetId (required), x, y, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a distinct resource and action. Widget-specific create/update tools are clearly separated by widget type, and the three arrow tools are differentiated by connection mode.
All tool names follow a consistent verb_noun pattern (list_, get_, create_, update_, delete_, connect_). The two batch variants are clearly named, and no style mixing occurs.
20 tools is on the heavier side but justified for covering workspaces, rooms, murals, and a variety of widget types. The count is slightly over the ideal range but not excessive.
Core workflows are covered: listing and creating murals, reading and creating widgets, updating sticky notes/text/shapes/areas, and deleting any widget. Minor gaps exist (no update_image, no delete_mural or update_mural), but these are not blocking for typical use.
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for Product Management
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Siftable MCP server for governed work, knowledge, calendar, people, datasets, and Vault.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for controlling Miro whiteboards with AI assistants. Create and manage stickies, shapes, frames, connectors, and more.8832MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables Claude AI to programmatically create and manipulate Miro boards via the Miro API with OAuth2 authentication. Supports 14 tools for board, item, and connector operations.-
- AlicenseAqualityDmaintenanceEnables interaction with Miro boards via MCP tools, supporting listing items, creating stickies, frames, shapes, connectors, and manipulating mind maps.13MIT
- FlicenseAqualityDmaintenanceMCP server for interacting with Mural's public API, enabling browsing and management of workspaces, rooms, murals, and widgets within Mural.23-