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

1. Node.js: Version 18 or higher

2. Mural Account: Access to Mural with workspace permissions

3. Mural OAuth App: Register an app at Mural Developer Portal

Installation

Option 1: Install from npm (Recommended)

Option 2: Install from source

1. Clone and install dependencies:

2. Build the project:

Setup

1. Set up environment variables:

Configuration

Environment Variables

Create a .env file with the following variables:

Mural OAuth App Setup

1. Visit Mural Developer Portal

2. Create a new application

3. Set the redirect URI to http://localhost:3000/callback (or your custom URI)

4. Note your Client ID and Client Secret

5. Configure the required scopes: workspaces:read

Usage

With Claude Desktop

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

Standalone Usage

Run the server directly:

Development

For development with hot reloading:

Authentication Flow

1. First Run: The server will open a browser window for OAuth authentication

2. Login: Complete the OAuth flow in your browser

3. Token Storage: Tokens are securely stored locally in ~/.mural-mcp-tokens.json

4. 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:

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

1. Token Expired: Use the clear-auth tool to clear tokens and re-authenticate

2. Invalid Client ID: Verify your MURAL_CLIENT_ID in the environment variables

3. Redirect URI Mismatch: Ensure the redirect URI matches your Mural app configuration

Connection Issues

1. Network: Ensure you can reach https://app.mural.co

2. Firewall: Port 3000 must be available for OAuth callback

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

Building

Testing

Test the server manually:

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

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