# mcp-interactive-ui-server

<!-- mcp-name: mcp-interactive-ui-server -->

[![PyPI version](https://badge.fury.io/py/mcp-interactive-ui-server.svg)](https://pypi.org/project/mcp-interactive-ui-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**MCP Apps UI toolkit** — forms, dashboards, charts, tables for AI agents to render interactive UIs.

## What Are MCP Apps?

MCP Apps is a 2026 extension to the Model Context Protocol that enables AI agents to go beyond text responses and render **interactive user interfaces** directly within MCP-compatible clients.

Instead of returning plain text or markdown, agents can generate structured UI schemas that clients render as native components — forms, dashboards, charts, tables, and multi-step wizards. This bridges the gap between conversational AI and application-level interactivity.

### Why This Matters

- **Agents become app builders**: Instead of describing data, agents can present it visually with charts, dashboards, and tables
- **Structured data collection**: Forms and wizards let agents gather complex user input with validation
- **Richer interactions**: Toggles, buttons, accordions, and tabs embedded directly in responses
- **Client-agnostic**: The JSON schema approach works across any MCP client that supports UI rendering

## Tools (6)

| Tool | Description |
|------|------------|
| `create_form` | Generate interactive forms with text, number, select, checkbox, date fields and validation |
| `create_dashboard` | Build grid-based dashboards with stat cards, charts, tables, progress bars |
| `create_chart` | Define charts (bar, line, pie, scatter, area, donut, heatmap) with data and styling |
| `create_table` | Create sortable, filterable, paginated tables from headers and row data |
| `create_wizard` | Multi-step form wizards with per-step validation and progress tracking |
| `render_markdown` | Enhanced markdown with embedded interactive elements (buttons, toggles, inputs, tabs) |

## Installation

```bash
pip install mcp-interactive-ui-server
```

## Quick Start

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "interactive-ui": {
      "command": "interactive-ui-server"
    }
  }
}
```

### Cursor / Windsurf

Add to your MCP settings:

```json
{
  "mcpServers": {
    "interactive-ui": {
      "command": "interactive-ui-server"
    }
  }
}
```

### With uvx (no install needed)

```json
{
  "mcpServers": {
    "interactive-ui": {
      "command": "uvx",
      "args": ["mcp-interactive-ui-server"]
    }
  }
}
```

## Usage Examples

### Create a Contact Form

```
Agent: create_form("Contact Us", [
    {"label": "Name", "type": "text", "required": true},
    {"label": "Email", "type": "email", "required": true},
    {"label": "Subject", "type": "select", "options": ["General", "Support", "Sales"]},
    {"label": "Message", "type": "textarea", "rows": 6}
])
```

### Build a Sales Dashboard

```
Agent: create_dashboard("Q1 Sales", [
    {"type": "stat_card", "title": "Revenue", "value": "$142K", "trend": "up", "change": "+12%"},
    {"type": "stat_card", "title": "Orders", "value": "1,247", "trend": "up", "change": "+8%"},
    {"type": "chart", "title": "Monthly Sales", "chart_type": "bar",
     "data": {"labels": ["Jan","Feb","Mar"], "datasets": [{"label": "Sales", "values": [42,51,49]}]}},
    {"type": "progress_bar", "title": "Quarterly Target", "value": 72, "max": 100}
])
```

### Generate a Chart

```
Agent: create_chart("pie",
    {"labels": ["Chrome", "Firefox", "Safari", "Edge"], "values": [65, 15, 12, 8]},
    title="Browser Market Share"
)
```

### Interactive Markdown Report

```
Agent: render_markdown(
    "# Status Report\n\nSystem health: {{status_badge}}\n\n{{details}}\n\n{{action_btn}}",
    [
        {"type": "badge", "id": "status_badge", "text": "Healthy", "color": "green"},
        {"type": "accordion", "id": "details", "title": "View Details", "content": "All 12 services operational."},
        {"type": "button", "id": "action_btn", "label": "Run Diagnostics", "action": "diagnose"}
    ]
)
```

## UI Schema

All tools return structured JSON following the `mcp-ui` schema specification:

```json
{
  "$schema": "mcp-ui/<component>/v1",
  "type": "<component_type>",
  "title": "...",
  "...": "component-specific properties",
  "metadata": {
    "created_at": "ISO timestamp",
    "version": "1.0"
  }
}
```

Schema types: `form`, `dashboard`, `chart`, `table`, `wizard`, `enhanced_markdown`

## Requirements

- Python 3.10+
- MCP SDK (`mcp[cli]>=1.0.0`)

## License

MIT