home / mcp / mural mcp server

Mural MCP Server

Provides MCP-based integration with Mural to list workspaces and manage OAuth tokens securely.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "cogell-mural-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mural-mcp/build/index.js"
      ],
      "env": {
        "MURAL_CLIENT_ID": "your_client_id_here",
        "MURAL_REDIRECT_URI": "http://localhost:3000/callback",
        "MURAL_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

You’re about to set up a Model Context Protocol (MCP) server that lets an AI assistant interact with Mural workspaces through OAuth 2.0 authentication. This server focuses on listing workspaces and securely managing authentication, enabling seamless integration with Mural from your MCP-enabled client.

How to use

Use the MCP server by running it locally or integrating it into an MCP client configuration. The server supports listing workspaces you have access to and retrieving detailed information about a specific workspace. It handles OAuth 2.0 authentication with PKCE, automatically refreshing tokens and storing them securely for subsequent requests.

Key capabilities you can invoke through your MCP client: list-workspaces to fetch all accessible workspaces, get-workspace to obtain details about a particular workspace, test-connection to verify access to the Mural API and authentication status, and clear-auth to reset stored tokens.

How to install

Prerequisites you need before installing the MCP server:

Node.js 18 or higher
A Mural account with workspace permissions
A Mural OAuth app registered in the Mural Developer Portal

Install from npm (recommended) for a quick start, or install from source if you want to build locally.

npm install -g mural-mcp
# or
pnpm add -g mural-mcp

Additional sections

Configuration and setup are tailored for secure OAuth integration and smooth operation with Mural. You’ll provide your Mural app’s client ID and optionally a client secret. The server can store tokens securely and refresh them automatically.

Environment variables you configure for the MCP server include your Mural client credentials and redirect URI. These are used during the OAuth flow to obtain and refresh access tokens.

Security considerations include using PKCE for OAuth, secure local token storage, HTTPS for API communications, and scoped access limited to necessary permissions.

If you encounter authentication or connection issues, re-authenticate, verify your client credentials and redirect URI, and ensure you can reach Mural’s API endpoints over the network.

Development notes: you can run a development workflow with hot reloading to iterate on the MCP server features.

Notes on configuration examples

stand-alone usage examples show how to start the server locally and how to configure an external MCP client to launch the server process. Use the exact commands shown to ensure proper behavior and token handling.

# Standalone start
export MURAL_CLIENT_ID=your_client_id_here
export MURAL_CLIENT_SECRET=your_client_secret_here

pnpm start
```

```bash
# Development with hot reloading
pnpm run dev

Available tools

list-workspaces

List all workspaces the authenticated user has access to. Returns workspace summaries including IDs and names.

get-workspace

Retrieve detailed information for a specific workspace by ID, including metadata and permissions.

test-connection

Test the connection to the Mural API and verify that authentication is functioning correctly.

clear-auth

Clear locally stored authentication tokens to reset the authentication state.