Mural MCP Server

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)

Board Editing — Read (2 tools)

Navigation (4 tools)

Mural Management (1 tool)

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/bg instead of width/height/backgroundColor)
• Batch summaries — create tools return {summary, count, ids, preview} instead of full object dumps
• Pagination — get_widgets defaults to 50 items with cursor-based pagination
• Server-side validation — shape types validated server-side (no bloated enums in schema)

Prerequisites

1. Register a Mural App

1. Go to app.mural.co → click your avatar → "Create and manage apps"
2. Click "New app"
3. Set the redirect URL to: http://localhost:9876/callback
4. Note 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 build

3. One-Time OAuth Authentication

export MURAL_CLIENT_ID=your_client_id
export MURAL_CLIENT_SECRET=your_client_secret
npm run auth

This 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.js

Set 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 Mural

Architecture

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 efficiency

• Transport: stdio (no HTTP server at runtime)
• Auth: OAuth2 + PKCE, tokens stored in ~/.mural-mcp/tokens.json, auto-refresh
• API: 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, startRefId is the widget the arrowhead points TO, and endRefId is the tail. The arrowhead renders at the first point in the points array.
• Sticky note styles on creation: Only fontSize and textAlign can be set during creation. backgroundColor must 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_widgets may fail with WIDGET_SIZE_INVALID when source and target are nearly vertically aligned (near-zero arrow width). Use create_arrow (freeform) as a fallback.

License

MIT