\n \n
\n ![\"Server](\"https://img.shields.io/npm/v/@mcp-ui/server?label=server&color=green\")
![\"Client](\"https://img.shields.io/npm/v/@mcp-ui/client?label=client&color=blue\")
![\"Ruby](\"https://img.shields.io/gem/v/mcp_ui_server\")
![\"Python](\"https://img.shields.io/pypi/v/mcp-ui-server?label=python&color=yellow\")
![\"Discord\"](\"https://img.shields.io/discord/1401195140436983879?logo=discord&label=discord\")
![\"MCP](\"https://img.shields.io/endpoint?url=https://gitmcp.io/badge/idosal/mcp-ui\"){kind=icon}
\n What's mcp-ui? •\n Core Concepts •\n Installation •\n Getting Started •\n Walkthrough •\n Examples •\n Supported Hosts •\n Security •\n Roadmap •\n Contributing •\n License\n
\n\n----\n\n**`mcp-ui`** brings interactive web components to the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP). Deliver rich, dynamic UI resources directly from your MCP server to be rendered by the client. Take AI interaction to the next level!\n\n> *This project is an experimental community playground for MCP UI ideas. Expect rapid iteration and enhancements!*\n\n\n \n
\n\n## 💡 What's `mcp-ui`?\n\n`mcp-ui` is a playground for the open spec of UI over MCP. It offers a collection of community SDKs comprising:\n\n* **`@mcp-ui/server` (TypeScript)**: Utilities to generate UI resources (`UIResource`) on your MCP server.\n* **`@mcp-ui/client` (TypeScript)**: UI components (e.g., `Hello, MCP UI!
' },\n encoding: 'text',\n });\n\n // External URL\n const externalUrlResource = createUIResource({\n uri: 'ui://greeting/1',\n content: { type: 'externalUrl', iframeUrl: 'https://example.com' },\n encoding: 'text',\n });\n\n // remote-dom\n const remoteDomResource = createUIResource({\n uri: 'ui://remote-component/action-button',\n content: {\n type: 'remoteDom',\n script: `\n const button = document.createElement('ui-button');\n button.setAttribute('label', 'Click me for a tool call!');\n button.addEventListener('press', () => {\n window.parent.postMessage({ type: 'tool', payload: { toolName: 'uiInteraction', params: { action: 'button-click', from: 'remote-dom' } } }, '*');\n });\n root.appendChild(button);\n `,\n framework: 'react', // or 'webcomponents'\n },\n encoding: 'text',\n });\n ```\n\n2. **Client-side**: Render in your MCP host\n\n ```tsx\n import React from 'react';\n import { UIResourceRenderer } from '@mcp-ui/client';\n\n function App({ mcpResource }) {\n if (\n mcpResource.type === 'resource' &&\n mcpResource.resource.uri?.startsWith('ui://')\n ) {\n return (\nUnsupported resource
;\n }\n ```\n\n### Python\n\n**Server-side**: Build your UI resources\n\n ```python\n from mcp_ui_server import create_ui_resource\n\n # Inline HTML\n html_resource = create_ui_resource({\n \"uri\": \"ui://greeting/1\",\n \"content\": { \"type\": \"rawHtml\", \"htmlString\": \"Hello, from Python!
\" },\n \"encoding\": \"text\",\n })\n\n # External URL\n external_url_resource = create_ui_resource({\n \"uri\": \"ui://greeting/2\",\n \"content\": { \"type\": \"externalUrl\", \"iframeUrl\": \"https://example.com\" },\n \"encoding\": \"text\",\n })\n ```\n\n### Ruby\n\n**Server-side**: Build your UI resources\n\n ```ruby\n require 'mcp_ui_server'\n\n # Inline HTML\n html_resource = McpUiServer.create_ui_resource(\n uri: 'ui://greeting/1',\n content: { type: :raw_html, htmlString: 'Hello, from Ruby!
' },\n encoding: :text\n )\n\n # External URL\n external_url_resource = McpUiServer.create_ui_resource(\n uri: 'ui://greeting/2',\n content: { type: :external_url, iframeUrl: 'https://example.com' },\n encoding: :text\n )\n\n # remote-dom\n remote_dom_resource = McpUiServer.create_ui_resource(\n uri: 'ui://remote-component/action-button',\n content: {\n type: :remote_dom,\n script: \"\n const button = document.createElement('ui-button');\n button.setAttribute('label', 'Click me from Ruby!');\n button.addEventListener('press', () => {\n window.parent.postMessage({ type: 'tool', payload: { toolName: 'uiInteraction', params: { action: 'button-click', from: 'ruby-remote-dom' } } }, '*');\n });\n root.appendChild(button);\n \",\n framework: :react,\n },\n encoding: :text\n )\n ```\n\n## 🚶 Walkthrough\n\nFor a detailed, simple, step-by-step guide on how to integrate `mcp-ui` into your own server, check out the full server walkthroughs on the [mcp-ui documentation site](https://mcpui.dev):\n\n- **[TypeScript Server Walkthrough](https://mcpui.dev/guide/server/typescript/walkthrough)**\n- **[Ruby Server Walkthrough](https://mcpui.dev/guide/server/ruby/walkthrough)**\n- **[Python Server Walkthrough](https://mcpui.dev/guide/server/python/walkthrough)**\n\nThese guides will show you how to add a `mcp-ui` endpoint to an existing server, create tools that return UI resources, and test your setup with the `ui-inspector`!\n\n## 🌍 Examples\n\n**Client Examples**\n* [Goose](https://github.com/block/goose) - open source AI agent that supports `mcp-ui`.\n* [LibreChat](https://github.com/danny-avila/LibreChat) - enhanced ChatGPT clone that supports `mcp-ui`.\n* [ui-inspector](https://github.com/idosal/ui-inspector) - inspect local `mcp-ui`-enabled servers.\n* [MCP-UI Chat](https://github.com/idosal/scira-mcp-ui-chat) - interactive chat built with the `mcp-ui` client. Check out the [hosted version](https://scira-mcp-chat-git-main-idosals-projects.vercel.app/)!\n* MCP-UI RemoteDOM Playground (`examples/remote-dom-demo`) - local demo app to test RemoteDOM resources\n* MCP-UI Web Component Demo (`examples/wc-demo`) - local demo app to test the Web Component integration in hosts\n\n**Server Examples**\n* **TypeScript**: A [full-featured server](examples/server) that is deployed to a hosted environment for easy testing.\n * **[`typescript-server-demo`](./examples/typescript-server-demo)**: A simple Typescript server that demonstrates how to generate UI resources.\n * **server**: A [full-featured Typescript server](examples/server) that is deployed to a hosted Cloudflare environment for easy testing.\n * **HTTP Streaming**: `https://remote-mcp-server-authless.idosalomon.workers.dev/mcp`\n * **SSE**: `https://remote-mcp-server-authless.idosalomon.workers.dev/sse`\n* **Ruby**: A barebones [demo server](/examples/ruby-server-demo) that shows how to use `mcp_ui_server` and `mcp` gems together.\n* **Python**: A simple [demo server](/examples/python-server-demo) that shows how to use the `mcp-ui-server` Python package.\n* [XMCP](https://github.com/basementstudio/xmcp/tree/main/examples/mcp-ui) - Typescript MCP framework with `mcp-ui` starter example.\n\nDrop those URLs into any MCP-compatible host to see `mcp-ui` in action. For a supported local inspector, see the [ui-inspector](https://github.com/idosal/ui-inspector).\n\n## 💻 Supported Hosts\n\n`mcp-ui` is supported by a growing number of MCP-compatible clients. Feature support varies by host:\n\n| Host | Rendering | UI Actions | Notes\n| :-------- | :-------: | :--------: | :--------: |\n| [Nanobot](https://www.nanobot.ai/) | ✅ | ✅ |\n| [ChatGPT](https://chatgpt.com/) | ✅ | ⚠️ | [Guide](https://mcpui.dev/guide/apps-sdk)\n| [Postman](https://www.postman.com/) | ✅ | ⚠️ |\n| [Goose](https://block.github.io/goose/) | ✅ | ⚠️ |\n| [LibreChat](https://www.librechat.ai/) | ✅ | ⚠️ |\n| [Smithery](https://smithery.ai/playground) | ✅ | ❌ |\n| [MCPJam](https://www.mcpjam.com/) | ✅ | ❌ |\n| [fast-agent](https://fast-agent.ai/mcp/mcp-ui/) | ✅ | ❌ |\n| [VSCode](https://github.com/microsoft/vscode/issues/260218) (TBA) | ? | ? |\n\n**Legend:**\n- ✅: Supported\n- ⚠️: Partial Support\n- ❌: Not Supported (yet)\n\n## 🔒 Security\nHost and user security is one of `mcp-ui`'s primary concerns. In all content types, the remote code is executed in a sandboxed iframe.\n\n## 🛣️ Roadmap\n\n- [X] Add online playground\n- [X] Expand UI Action API (beyond tool calls)\n- [X] Support Web Components\n- [X] Support Remote-DOM\n- [ ] Add component libraries (in progress)\n- [ ] Add SDKs for additional programming languages (in progress; Ruby, Python available)\n- [ ] Support additional frontend frameworks\n- [ ] Add declarative UI content type\n- [ ] Support generative UI?\n \n## Core Team\n`mcp-ui` is a project by [Ido Salomon](https://x.com/idosal1), in collaboration with [Liad Yosef](https://x.com/liadyosef).\n\n## 🤝 Contributing\n\nContributions, ideas, and bug reports are welcome! See the [contribution guidelines](https://github.com/idosal/mcp-ui/blob/main/.github/CONTRIBUTING.md) to get started.\n\n## 📄 License\n\nApache License 2.0 © [The MCP-UI Authors](LICENSE)\n\n## Disclaimer\n\nThis project is provided \"as is\", without warranty of any kind. The `mcp-ui` authors and contributors shall not be held liable for any damages, losses, or issues arising from the use of this software. Use at your own risk.","users":{}}