create-chatgpt-app

Create ChatGPT MCP widget apps with one command.

Quick Start

npx create-chatgpt-app my-app
cd my-app
pnpm install
pnpm run build

What You Get

Running npx create-chatgpt-app creates a complete ChatGPT MCP widget application with:

🎨 6 Example Widgets

1. pizzaz - Interactive map with pizza locations
2. pizzaz-albums - Photo album viewer with fullscreen support
3. pizzaz-carousel - Horizontal scrolling carousel
4. pizzaz-list - Simple list view
5. solar-system - 3D solar system visualization
6. todo - Todo list manager

🏗️ Complete Framework

• MCP Widget Framework - Automatic tool/resource generation
• React Components - Modern React 19 with hooks
• TypeScript - Full type safety
• Vite - Fast build tooling
• Tailwind CSS - Utility-first styling

📚 Documentation

• AGENTS.md - Complete guide for AI coding agents
• FRAMEWORK.md - Technical architecture documentation
• README.md - Quick start and usage guide

Usage

Create a new app

# With project name
npx create-chatgpt-app my-app

# Interactive mode
npx create-chatgpt-app

Run your app

You need to run 3 processes:

# Terminal 1: Assets server (serves widget JavaScript/CSS)
pnpm run serve

# Terminal 2: MCP server (handles ChatGPT communication)
cd server
pnpm start

# Terminal 3: Public tunnel (exposes server to ChatGPT)
ngrok http 8000

Use in ChatGPT

1. Copy the ngrok URL (e.g., https://xxx.ngrok-free.app)
2. Open ChatGPT (with GPT-4o or ChatGPT Plus)
3. Enable "Developer Mode" in settings
4. Add your MCP server URL
5. Start chatting! Ask ChatGPT to show you widgets

Example prompts:

• "Show me the pizza map"
• "Display the photo album"
• "Create a todo list"

Creating Custom Widgets

The framework makes it incredibly easy to create new widgets:

1. Create Component

// src/components/my-widget/index.jsx
import React from 'react';
import { createRoot } from 'react-dom/client';

function MyWidget() {
  return <div>Hello World!</div>;
}

const rootElement = document.getElementById('my-widget-root');
if (rootElement) {
  createRoot(rootElement).render(<MyWidget />);
}

2. Add Widget Definition

// server/src/server.ts
{
  component: "my-widget",
  title: "My Widget",
  schema: z.object({
    message: z.string().describe("Message to display")
  }),
  handler: async (args) => ({
    text: "Showing widget!",
    data: args
  })
}

3. Build & Restart

pnpm run build
cd server && pnpm start

Done! See docs/AGENTS.md for detailed instructions.

Features

For Developers

• 🚀 Zero Config - Start building widgets immediately
• 📦 Monorepo Setup - Organized workspace with pnpm
• 🔥 Hot Reload - Fast development with Vite
• 🎯 Type Safe - Full TypeScript support
• 🎨 Modern Stack - React 19, Tailwind CSS, Vite

For AI Agents

• 🤖 AI-Friendly - Comprehensive documentation for AI coding tools
• 📝 Clear Patterns - Consistent conventions throughout
• 🔧 Simple API - Minimal boilerplate, maximum productivity

Requirements

• Node.js 18.0.0 or higher
• pnpm (recommended), npm, or yarn
• ngrok for exposing server to ChatGPT

Project Structure

my-app/
├── src/components/          # Widget components
├── server/                  # MCP server
│   ├── src/
│   │   ├── framework/      # MCP framework code
│   │   └── server.ts       # Widget definitions
│   └── package.json
├── docs/                    # Documentation
├── build-all.mts           # Build script
├── vite.config.mts         # Vite configuration
└── package.json

Examples

Check out the example widgets included in every new project:

• Map Widget (pizzaz) - Shows how to integrate external libraries (Mapbox)
• Album Widget (pizzaz-albums) - Demonstrates complex state management
• Carousel Widget (pizzaz-carousel) - Horizontal scrolling with Embla
• Todo Widget - Full CRUD operations with local state

Learn More

• MCP Protocol - Model Context Protocol
• OpenAI Apps SDK - OpenAI Apps documentation
• React Documentation - React 19 documentation

License

MIT

Support

For issues and questions:

• Check docs/AGENTS.md for detailed guides
• Review example widgets in src/components/
• See docs/FRAMEWORK.md for technical details