mural-mcp

Mural MCP Server

A Model Context Protocol (MCP) server that provides integration with the Mural visual collaboration platform. This server enables AI assistants to interact with Mural workspaces through OAuth 2.0 authentication.

Note: This is v0.0.1 - an early MVP release focused on workspace listing functionality. More features are planned for future releases.

Features

• OAuth 2.0 Authentication: Secure authentication with PKCE support
• Workspace Management: List and retrieve workspace information
• MCP Compliance: Full Model Context Protocol compatibility
• Token Management: Automatic token refresh and secure storage

Tools Available

• list-workspaces: List all workspaces the authenticated user has access to
• get-workspace: Get detailed information about a specific workspace
• test-connection: Test the connection to Mural API and verify authentication
• clear-auth: Clear stored authentication tokens

Prerequisites

• Node.js: Version 18 or higher
• Mural Account: Access to Mural with workspace permissions
• Mural OAuth App: Register an app at Mural Developer Portal

Installation

Option 1: Install from npm (Recommended)

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

Option 2: Install from source

• Clone and install dependencies:

git clone https://github.com/your-username/mural-mcp.git
cd mural-mcp
pnpm install

• Build the project:

pnpm run build

Setup

• Set up environment variables:

cp .env.example .env
# Edit .env with your Mural OAuth credentials

Configuration

Environment Variables

Create a .env file with the following variables:

# Required: Your Mural app's client ID
MURAL_CLIENT_ID=your_client_id_here

# Optional: Your Mural app's client secret (recommended)
MURAL_CLIENT_SECRET=your_client_secret_here

# Optional: OAuth redirect URI (defaults to http://localhost:3000/callback)
MURAL_REDIRECT_URI=http://localhost:3000/callback

Mural OAuth App Setup

• Visit Mural Developer Portal
• Create a new application
• Set the redirect URI to http://localhost:3000/callback (or your custom URI)
• Note your Client ID and Client Secret
• Configure the required scopes: workspaces:read

Usage

With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

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

Standalone Usage

Run the server directly:

# Set environment variables
export MURAL_CLIENT_ID=your_client_id_here
export MURAL_CLIENT_SECRET=your_client_secret_here

# Start the server
pnpm start

Development

For development with hot reloading:

pnpm run dev

Authentication Flow

• First Run: The server will open a browser window for OAuth authentication
• Login: Complete the OAuth flow in your browser
• Token Storage: Tokens are securely stored locally in ~/.mural-mcp-tokens.json
• Auto-Refresh: Access tokens are automatically refreshed when needed

API Endpoints Used

• Authorization: https://app.mural.co/api/public/v1/authorization/oauth2/
• Token Exchange: https://app.mural.co/api/public/v1/authorization/oauth2/token
• Workspaces: https://app.mural.co/api/public/v1/workspaces

Example Usage

Once configured, you can use the tools through your MCP client:

Human: List my Mural workspaces
Assistant: I'll list your Mural workspaces using the list-workspaces tool.

[Tool executes and returns workspace data]

Security Considerations

• PKCE: Uses Proof Key for Code Exchange for enhanced OAuth security
• Token Storage: Tokens are stored locally in the user's home directory
• HTTPS: All API communications use HTTPS
• Scope Limitation: Requests only necessary OAuth scopes

Troubleshooting

Authentication Issues

• Token Expired: Use the clear-auth tool to clear tokens and re-authenticate
• Invalid Client ID: Verify your MURAL_CLIENT_ID in the environment variables
• Redirect URI Mismatch: Ensure the redirect URI matches your Mural app configuration

Connection Issues

• Network: Ensure you can reach https://app.mural.co
• Firewall: Port 3000 must be available for OAuth callback
• Test Connection: Use the test-connection tool to verify API access

Common Error Messages

• Missing required environment variable: MURAL_CLIENT_ID: Set the required environment variable
• OAuth token exchange failed: Check your client credentials and redirect URI
• Mural API request failed: HTTP 401: Token expired or invalid, clear auth and re-authenticate
• Mural API request failed: HTTP 403: Insufficient permissions or invalid scope

Development

Project Structure

mural-mcp/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── oauth.ts          # OAuth 2.0 implementation
│   ├── mural-client.ts   # Mural API client
│   └── types.ts          # TypeScript interfaces
├── build/                # Compiled output
├── spec/                 # Documentation
└── package.json

Building

# Clean build
rm -rf build && pnpm run build

# Development build with watch
pnpm run dev

Testing

Test the server manually:

# Build and run
pnpm run build
node build/index.js

# In another terminal, test with MCP inspector
npx @modelcontextprotocol/inspector node build/index.js

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests if applicable
• Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Check the troubleshooting section above
• Review Mural API documentation
• Create an issue in the repository