DashWebMCP

MCP (Model Context Protocol) bridge for Dash applications - Expose any Dash page as an MCP server for AI agents.

Overview

DashWebMCP enables AI agents (Claude, GPT, Cursor, etc.) to interact with your Dash dashboards through the Model Context Protocol. It provides:

• WebSocket bridge between browser tabs and MCP server
• Automatic tool registration from browser pages
• Built-in UI tools for common interactions (click, setValue, getText, etc.)
• Custom tool registration via JavaScript API
• Human-in-the-loop confirmation support

Installation

From GitHub (recommended until published to PyPI)

# With MCP SDK support
pip install "dashwebmcp[mcp] @ git+https://github.com/Cemberk/dashwebmcp.git"

# With server (uvicorn) support
pip install "dashwebmcp[server] @ git+https://github.com/Cemberk/dashwebmcp.git"

# Everything (recommended)
pip install "dashwebmcp[all] @ git+https://github.com/Cemberk/dashwebmcp.git"

From Local Clone

git clone https://github.com/Cemberk/dashwebmcp.git
cd dashwebmcp
pip install -e .[all]  # Editable install with all dependencies

From PyPI (when published)

pip install dashwebmcp[all]

Quick Start

Server Setup

import contextlib
from starlette.applications import Starlette
from starlette.routing import Mount
from dashwebmcp import MCPRelay, create_mcp_routes, mcp_lifespan

# Create MCP relay
mcp_relay = MCPRelay()

# Create lifespan handler
@contextlib.asynccontextmanager
async def lifespan(app):
    async with mcp_lifespan(app, mcp_relay):
        yield

# Create routes
routes = create_mcp_routes(mcp_relay)

# Add to your Starlette/ASGI app
app = Starlette(routes=routes, lifespan=lifespan)

Include JavaScript Bridge

Copy the JavaScript bridge to your Dash assets folder:

from dashwebmcp import get_js_bridge_path
import shutil

# Copy to your assets folder
shutil.copy(get_js_bridge_path(), "assets/dash_mcp_bridge.js")

Or include the content directly:

from dashwebmcp import get_js_bridge_content

js_content = get_js_bridge_content()

Connect AI Agent

Configure your AI agent (e.g., Claude Desktop) with the MCP endpoint:

{
  "mcpServers": {
    "my-dashboard": {
      "url": "http://localhost:8050/mcp"
    }
  }
}

Built-in Tools

The JavaScript bridge provides these tools automatically:

Tool	Description	Read-only
page.info	Get page URL, title, viewport size	Yes
page.snapshot	Get page DOM snapshot	Yes
page.elements	List interactive elements	Yes
page.navigate	Navigate to a path	No
ui.getText	Get element text content	Yes
ui.waitFor	Wait for element to appear	Yes
ui.setValue	Set input value	No
ui.click	Click an element	No
ui.select	Select dropdown option	No
ui.scrollTo	Scroll element into view	No

Custom Tools

Register custom tools from your Dash pages:

window.DashMCP.registerTool(
    'getData',
    {
        description: 'Get data from the current dashboard',
        inputSchema: {
            type: 'object',
            properties: {
                format: {
                    type: 'string',
                    enum: ['json', 'csv'],
                    description: 'Output format'
                }
            }
        },
        annotations: { readOnly: true }
    },
    async ({ format }) => {
        const data = await fetchDashboardData();
        return format === 'csv' ? toCsv(data) : data;
    }
);

Tool Namespacing

Tools are namespaced by browser session:

• dash.sessions.list - List all active sessions
• dash.<session_id>.<tool_name> - Session-specific tools

Example:

dash.tab_abc123.page.info
dash.tab_abc123.getData

Human-in-the-Loop

Enable confirmation dialogs for tool calls:

// Confirm all tool calls
window.DashMCP.policy.confirmAll = true;

// Only confirm mutations (non-readonly tools)
window.DashMCP.policy.confirmMutations = true;

Configuration

Environment Variables

• MCP_ALLOWED_ORIGINS - Comma-separated list of allowed WebSocket origins

export MCP_ALLOWED_ORIGINS="http://localhost:8050,https://mydash.example.com"

Debug Mode

Enable verbose logging:

window.DashMCP.debug = true;

Architecture

AI Agent (Claude/GPT)
        ↓
   MCP Protocol (HTTP)
        ↓
   MCP Relay Server
        ↓
   WebSocket Bridge
        ↓
   Browser Tab (JavaScript)
        ↓
   Tool Execution
        ↓
   Result → Agent

Security

• Tools execute in browser context only
• Server never runs tool logic directly
• WebSocket origin validation
• Optional human confirmation
• Read-only annotations for safe tools
• Automatic protocol fix: WebSocket connections automatically use wss:// on HTTPS pages

Checking Availability

from dashwebmcp import DASHWEBMCP_AVAILABLE, MCP_AVAILABLE

if DASHWEBMCP_AVAILABLE:
    print("dashwebmcp package is installed")
    
if MCP_AVAILABLE:
    print("MCP SDK is also installed")

Changelog

0.1.1

• Added DASHWEBMCP_AVAILABLE flag to exports for easy availability checking
• Built-in WebSocket protocol fix: automatically converts ws:// to wss:// on HTTPS pages
• Fixes mixed content issues on production HTTPS deployments

0.1.0

• Initial release

License

MIT License