mcp-ui

What it is

A UI over MCP. Create next-gen UI experiences with the protocol and SDK!

How it works

The project provides:

• @mcp-ui/server (TypeScript): Create UI resources with createUIResource and integrate with registerAppTool and registerAppResource from the MCP Apps server.
• @mcp-ui/client (TypeScript): Render tool UIs via AppRenderer or legacy UIResourceRenderer for MCP-UI hosts.
• Platform adapters that translate MCP-UI postMessage protocol to host-specific APIs.

UI resources link tools to UIs via _meta.ui.resourceUri, and hosts fetch and render the UI alongside tool results.

UI Resource payload example shows a resource with uri, mimeType, and either text or blob content.

Getting started

Installation (TypeScript)

# using npm
npm install @mcp-ui/server @mcp-ui/client

# or pnpm
pnpm add @mcp-ui/server @mcp-ui/client

# or yarn
yarn add @mcp-ui/server @mcp-ui/client

Python and Ruby sections are present in the README, but commands are not repeated here beyond the TypeScript install.

Getting started (Code examples)

TypeScript server example shows creating a UI resource and registering a tool linking to that UI:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Interactive Widget</h1>' },
  encoding: 'text',
});

registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

registerAppTool(server, 'show_widget', {
  description: 'Show widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `Query: ${query}` }] };
});

Client-side rendering example uses AppRenderer:

import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: sandboxUrl }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => window.open(url)}
      onMessage={async (params) => console.log('Message:', params)}
    />
  );
}

Release history

Latest releases include:

• client/v7.1.1 (2026-05-09) with bug fix: cancel sandbox proxy iframe timeout on effect cleanup to prevent StrictMode unhan
• client/v7.1.0 (2026-05-01) with features: add hostInfo and hostCapabilities props to AppRenderer
• client/v7.0.0 (2026-03-12)
• client/v6.1.1 (2026-03-12)
• server/v6.1.0 (2026-02-13)

Traction

Stars: 5073, Forks: 391, Open issues: 59

License

Apache-2.0

Getting started (additional platforms)

Ruby: gem install mcp_ui_server Python: pip install mcp-ui-server