gptapps

Build ChatGPT apps in seconds.

npx gptapps init my-app

Overview

gptapps is a CLI toolkit for building ChatGPT applications with MCP (Model Context Protocol) servers. Create interactive tools that integrate seamlessly with ChatGPT, following OpenAI's official approach.

Installation

# Global installation
npm install -g gptapps

# Or use directly with npx
npx gptapps init my-app

Quick Start

# 1. Create your app
gptapps init my-chatgpt-app
cd my-chatgpt-app

# 2. Install dependencies
npm install

# 3. Build your tools
npm run build:tools

# 4. Build the MCP server
npm run build:server

# 5. Run the server
npm run dev:server

# 6. Expose locally with ngrok
ngrok http 8000

# 7. Add to ChatGPT
# Go to ChatGPT Settings > Apps and Connectors
# Add your ngrok URL: https://your-url.ngrok-free.app/mcp

How It Works

gptapps follows the MCP + Apps SDK pattern used by OpenAI:

1. Tools as separate files - Each tool is a standalone React component in src/tools/
2. Build process - Vite bundles each tool into versioned .html, .js, .css files
3. MCP server - Serves your tools and handles ChatGPT's tool calls
4. Widget rendering - ChatGPT renders your tools inline using the Apps SDK

Your app structure:

my-app/
├── src/
│   ├── tools/              # Your tool implementations
│   │   ├── my-tool/
│   │   │   └── index.tsx   # Tool component
│   │   └── another-tool/
│   │       └── index.tsx
│   ├── components/         # Shared UI components
│   ├── hooks/              # React hooks
│   └── utils/              # Utilities
├── server/
│   └── index.ts            # MCP server
└── dist/                   # Built tools (after build)

Commands

init [name]

Initialize a new ChatGPT app with MCP server included.

gptapps init my-app

Creates:

• React 18 + TypeScript
• Vite build system
• MCP server ready to go
• OpenAI integration hooks
• Example tools

add <components...>

Add components and utilities to your project.

# Add specific components
gptapps add button card carousel

# Add all components
gptapps add --all

list

Show available components and utilities.

# List all
gptapps list

# Show only installed
gptapps list --installed

# Filter by category
gptapps list --category display

Building & Deploying

Development

# Start dev server for tools UI
npm run dev

# Start MCP server
npm run dev:server

Production Build

# Build all tools
npm run build:tools

# Build MCP server
npm run build:server

The dist/ folder will contain your built tools as standalone HTML files that the MCP server serves.

Local Testing

Use ngrok to expose your local server:

# Run your server
npm run dev:server

# In another terminal
ngrok http 8000

Copy the ngrok URL (e.g., https://abc123.ngrok-free.app/mcp) and add it to ChatGPT:

1. Go to ChatGPT Settings
2. Navigate to Apps and Connectors
3. Click Add Connector
4. Paste your ngrok URL

What You Can Build

• Data visualization - Charts, graphs, dashboards
• Shopping assistants - Product catalogs with carts
• Content browsers - Articles, videos, galleries
• Productivity tools - Task managers, calendars
• Games - Quizzes, puzzles, interactive experiences

Component Library

Display & Layout

• list - Structured lists
• expandable-list - Zoom-to-detail lists
• card - Flexible cards
• carousel - Embla carousels with blur edges
• fade-gradient - Scroll fades
• gradual-blur - Blur overlays

Input & Controls

• button - Buttons with variants
• checkbox - Animated checkboxes

Navigation

• menu - Dropdown menus
• sidebar - Responsive sidebars
• inspector - Sliding panels

Feedback & Animation

• rating - Star ratings
• text-animation - Streaming text

Integration

• hooks - OpenAI widget hooks
• utils - Tailwind utilities

Creating a Tool

Example tool in src/tools/my-tool/index.tsx:

import React from 'react';
import { useWidgetProps } from '@/hooks';
import { List, ListHeader, ListItem } from '@/components/list';

function App() {
  const { data } = useWidgetProps<{ items: string[] }>();
  
  return (
    <List>
      <ListHeader title="My Tool" />
      {data.items.map((item, i) => (
        <ListItem key={i} title={item} />
      ))}
    </List>
  );
}

export default App;

The MCP server exposes this as a tool that ChatGPT can call.

MCP Server

Your server/index.ts handles:

• List tools - Advertises available tools
• Call tools - Executes tool logic
• Return widgets - Serves built tool HTML with metadata

The server returns _meta.openai/outputTemplate so ChatGPT knows how to render your tool.

Architecture

┌─────────────┐
│   ChatGPT   │
└──────┬──────┘
       │ MCP protocol
       ↓
┌─────────────┐
│ Your Server │  ← Serves tools from dist/
└──────┬──────┘
       │
       ↓
┌─────────────┐
│ Your Tools  │  ← Built React components
└─────────────┘

Requirements

• Node.js 14 or higher
• npm or yarn
• ngrok (for local testing)

Examples

Restaurant Finder

gptapps init restaurant-finder
cd restaurant-finder
gptapps add card carousel rating
# Build your restaurant browsing tool in src/tools/
npm run build:tools && npm run build:server

Shopping Assistant

gptapps init shop-assistant
cd shop-assistant
gptapps add expandable-list button card
# Build product catalog with cart
npm run build:tools && npm run build:server

Learn More

• OpenAI Apps SDK Examples - Official examples
• Model Context Protocol - MCP specification
• ChatGPT Platform Docs - Platform documentation

Contributing

Issues and pull requests welcome. For major changes, open an issue first.

License

MIT © 2025

Built for the ChatGPT platform. Learn more at platform.openai.com