mural-mcp-serveur

Mural MCP Serveur

A remote Model Context Protocol (MCP) server for the Mural visual collaboration platform. It lets an AI assistant read and write your workspaces, rooms, templates, murals and widgets, on your behalf.

The server is hosted: there is nothing to install and no secret on your machine. Your MCP client connects to one URL and signs you in to Mural in your browser.

https://mural-mcp-serveur.vercel.app/mcp

Features

• Workspaces and rooms: list workspaces and rooms (open rooms included), create rooms
• Templates: list or search a workspace's templates, create a mural from a template
• Murals: create (blank or from a template), read, update, archive, delete, duplicate, export and get the export's download URL
• Widgets: read, create and update sticky notes, shapes, arrows, text boxes, titles and areas; delete widgets
• Pagination: list tools follow the API cursor and return every item
• Compact responses: read tools return a trimmed projection of each object to save context; pass verbose: true for the full raw payload
• OAuth sign-in: the server is its own authorization server, with client registration (CIMD and DCR) and PKCE; Mural is the identity provider behind it

Connect an MCP client

Any MCP client that supports remote servers over Streamable HTTP with OAuth can connect. Give it the server URL; it registers itself and opens the sign-in page in your browser.

Before the first connection, the Mural app of this server must be enabled in your Mural workspace: see Mural access.

Claude Code

claude mcp add --transport http --scope user mural https://mural-mcp-serveur.vercel.app/mcp

Then run /mcp in Claude Code, pick mural and sign in.

Claude (web and desktop) and other clients

Add a custom connector (or remote MCP server) and paste https://mural-mcp-serveur.vercel.app/mcp as its URL. No client ID or secret is needed: the client registers itself.

What the sign-in does

1. Your browser opens this server's sign-in page, which sends you to Mural.
2. You sign in to Mural and approve the scopes the tools need.
3. Unless your client is claude.ai or ChatGPT, this server asks you to confirm which application gets access. It remembers your answer for 90 days.
4. Your client receives its tokens and the tools appear.

The client's access token lasts 10 minutes and is renewed silently. A connection lasts up to 90 days from sign-in, as long as Mural keeps accepting it; then your client asks you to sign in again. The clear-auth tool signs the connection out.

Upgrading from 1.x

Version 1.x ran on your machine (npx -y @florentleveque/mural-mcp-serveur) with your own Mural OAuth app. That npm package is deprecated: from 2.0, the server is hosted only.

1. Remove the old entry from your client. In Claude Code: claude mcp remove mural, with the name you gave it (add -s local, -s user or -s project if it exists in several scopes).
2. Connect to the hosted server as described above.
3. Delete ~/.mural-mcp-tokens.json, where 1.x kept your Mural tokens. The MURAL_CLIENT_ID and MURAL_CLIENT_SECRET of your own Mural app are no longer used.

Mural access: an Unlisted app

The server signs in to Mural through one Mural OAuth app, published as Unlisted: it is not in Mural's public app directory, and only people who have its listing link can see it.

Listing link: https://app.mural.co/me/integrations/listing/6ff63b23-e411-4e9a-a4c1-97f68f758474

To roll the server out in a Mural workspace:

1. A workspace admin opens the listing link while signed in to Mural and selects Enable in admin dashboard. Mural enables the app in that admin's workspace and opens the workspace settings at Apps, where the app is listed under Enabled Apps (tested with an admin of a single workspace).
2. Each member connects their own MCP client (see Connect an MCP client) and signs in with their own Mural account.

Not a workspace admin? Send the listing link to an admin of your workspace and ask them to enable the app.

Mural documents that admins with the link can enable the app in the workspaces they choose, not what a member can do in a workspace where it is not enabled: whether the sign-in or the API calls then fail is not verified. The app's owner reaches every workspace they belong to either way.

Tools Available

Authentication and utilities

• test-connection: Test the connection to the Mural API and verify authentication
• clear-auth: Sign this connection out (revokes its tokens and the Mural tokens behind them; the client must sign in again)
• check-user-scopes: Show the Mural scopes granted to this connection, and those the tools miss
• debug-api-response: Raw workspaces API response (troubleshooting)

Workspaces

• list-workspaces: List all workspaces the authenticated user has access to
• get-workspace: Get detailed information about a specific workspace

Rooms

• list-workspace-rooms: List a workspace's rooms (option openOnly)
• list-room-boards: List the murals within a room
• create-room: Create a room (open/private)

Templates

• list-workspace-templates: List a workspace's templates (default and custom), or search them by name
• create-mural-from-template: Create a mural in a room from a template

Murals

• list-workspace-boards: List a workspace's murals
• get-board: Get details of a specific mural
• create-mural: Create a blank mural in a room
• update-mural: Update a mural (title, status active/archived, dimensions, sharing...)
• delete-mural: Permanently delete a mural (irreversible)
• duplicate-mural: Duplicate a mural into a room
• export-mural: Start an asynchronous export of a mural in a given format (returns an exportId)
• download-export: Get the signed download URL of an export (no authentication needed to fetch it); returns ready:false while the export is not ready, so call it again until ready

Widgets

• get-mural-widgets: Get all widgets of a mural (paginated)
• get-mural-widget: Get a specific widget by id
• create-sticky-notes: Create sticky notes (up to 1000 per request)
• update-sticky-note: Update a sticky note
• create-shapes / create-arrows / create-text-boxes / create-titles / create-areas: Create the corresponding widgets
• update-widget: Update any widget by kind and id
• delete-widget: Permanently delete a widget by id

Write tools need the matching Mural scopes (rooms:write, murals:write, templates:write). The sign-in asks for all of them.

Privacy and security

• The Mural client secret lives on the server only. MCP clients never see a Mural token: they get this server's own tokens, encrypted, bound to its /mcp endpoint and valid 10 minutes.
• Your Mural tokens are kept server-side, encrypted, in an Upstash Redis database in Frankfurt. The server functions also run in Frankfurt (Vercel region fra1).
• The server stores no mural content: each tool call goes to the Mural API with your own Mural token, and the answer goes back to your client.

Design and rationale: docs/decisions/oauth-authorization-server.md.

Troubleshooting

• Mural refuses the sign-in: the app is probably not enabled in your workspace. See Mural access.
• "Sign in again" or HTTP 401: the connection expired, was signed out with clear-auth, or Mural revoked it. Reconnect from your client (/mcp in Claude Code).
• HTTP 403 on a write: check the granted scopes with check-user-scopes. Mural's free plan also limits what you can create (for example 3 murals per workspace, open rooms only); its error message says so.

Self-hosting and development

• Deploy your own instance on Vercel: docs/http-deployment.md.
• Try a branch on its preview deployment: docs/live-testing.md.
• Contribute: CONTRIBUTING.md.

Inspired by

This project is inspired by cogell/mural-mcp.

License

MIT License, see LICENSE.