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)

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).