Mural MCP

MCP server for working with Mural Public API v1 from MCP-compatible clients (Cursor, Claude Desktop, and other MCP hosts).
It supports browsing workspaces and rooms, creating/updating/deleting murals, and creating/updating/deleting mural widgets.

Description

This project exposes Mural operations as MCP tools by wrapping Mural's REST API with a Python server built on FastMCP.

Highlights:

• OAuth2 authentication using client_id, client_secret, and a long-lived refresh_token

• Automatic access token refresh before expiration

• Tooling for:

  • workspace/room/mural navigation

  • mural CRUD

  • widget CRUD (sticky notes, shapes, text, arrows, areas, comments)

Related MCP server: miro-mcp-server

Requirements

• Python >=3.11

• uv (recommended for dependency management and running)

• A Mural developer app with:

  • MURAL_CLIENT_ID

  • MURAL_CLIENT_SECRET

  • OAuth redirect URI configured in Mural

Installation

Clone the repository and install dependencies:

git clone <your-repo-url>
cd arcsen-mural-mcp
uv sync

Configuration

Create a .env file in the project root:

cp .env.example .env

Fill in:

MURAL_CLIENT_ID=your-client-id
MURAL_CLIENT_SECRET=your-client-secret
MURAL_REFRESH_TOKEN=your-refresh-token
# Optional but recommended:
MURAL_REDIRECT_URI=http://localhost:8080/callback

Get Initial Refresh Token (One-Time OAuth Setup)

If you only have client ID and secret, generate the first refresh token with:

./scripts/get_mural_refresh_token.sh

What it does:

1. Reads MURAL_CLIENT_ID and MURAL_CLIENT_SECRET from .env

2. Builds OAuth authorization URL

3. Prompts you for the returned authorization code

4. Exchanges code for tokens and prints MURAL_REFRESH_TOKEN=...

Then paste that value into your .env.

Note: redirect URI must match exactly between:

• your Mural app settings

• the authorization request

• the token exchange request

Run the MCP Server

Start server over stdio:

uv run main.py

This process is intended to be launched by an MCP host (rather than visited in a browser).

Connect to Claude Desktop

Edit:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Example:

{
  "mcpServers": {
    "mural": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/arcsen-mural-mcp",
        "main.py"
      ],
      "env": {
        "MURAL_CLIENT_ID": "your-client-id",
        "MURAL_CLIENT_SECRET": "your-client-secret",
        "MURAL_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Restart Claude Desktop after saving.

Available Tool Groups

The server includes the following tool categories:

• Navigation / Read

  • list_workspaces

  • list_rooms

  • list_murals_in_room

  • get_mural

  • get_mural_widgets

  • get_mural_widget

• Mural CRUD

  • create_mural

  • update_mural

  • delete_mural

• Widget Create

  • create_sticky_notes

  • create_shapes

  • create_titles

  • create_textboxes

  • create_arrow

  • create_area

  • create_comment

• Widget Update

  • update_sticky_note

  • update_shape

  • update_text

  • update_arrow

  • update_area

  • update_comment

• Widget Delete

  • delete_widget

Arrow Accuracy Tip

To avoid randomly placed arrows, prefer anchored connectors:

• Use create_arrow with start_ref_id and end_ref_id

• Use widget IDs from created/fetched source and target shapes

• Avoid relying only on raw x/y and points

Troubleshooting

• RuntimeError for missing env vars
  Ensure MURAL_CLIENT_ID, MURAL_CLIENT_SECRET, and MURAL_REFRESH_TOKEN are present.

• OAuth redirect shows "site can't be reached"
  This can still be fine if URL contains ?code=.... Copy the code from the URL and continue.

• OAuth redirect returns 404 on local server
  Usually means redirect reached your local server but no matching path exists. You can still copy code from the URL.

• No tools appear in Claude Desktop
  Validate JSON config, confirm absolute path, and restart Claude Desktop fully.

Development Notes

• Entry point: main.py

• Auth and token refresh logic: MuralClient class in main.py

• OAuth helper script: scripts/get_mural_refresh_token.sh

License

Add your project license here (for example, MIT).