Create MCP-Use apps with one command
npm install create-mcp-use-appš Create mcp-use App is the fastest way to scaffold a new MCP (Model Context Protocol) application. With just one command, you get a fully configured TypeScript project with hot reload, automatic inspector, and UI widget support - everything you need to build powerful MCP servers.
| Package | Description | Version |
| ---------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| mcp-use | Core MCP framework |  |
| @mcp-use/cli | Build tool for MCP apps |  |
| @mcp-use/inspector | Web-based MCP inspector |  |
---
Create a new MCP application in seconds:
``bash`
npx create-mcp-use-app my-mcp-server
cd my-mcp-server
npm run dev
That's it! Your MCP server is running at http://localhost:3000 with the inspector automatically opened in your browser.
---
Running create-mcp-use-app sets up a complete MCP development environment:
``
my-mcp-server/
āāā package.json # Pre-configured with all scripts
āāā tsconfig.json # TypeScript configuration
āāā .env.example # Environment variables template
āāā .gitignore # Git ignore rules
āāā README.md # Project documentation
āāā src/
ā āāā index.ts # MCP server entry point with example tools
āāā resources/ # UI widgets directory
ā āāā example-widget.tsx # Example React widget
āāā dist/ # Build output (generated)
| Feature | Description |
| ----------------------- | ------------------------------------------------- |
| š TypeScript | Full TypeScript setup with proper types |
| š„ Hot Reload | Auto-restart on code changes during development |
| š Auto Inspector | Inspector UI opens automatically in dev mode |
| šØ UI Widgets | React components that compile to standalone pages |
| š ļø Example Tools | Sample MCP tools, resources, and prompts |
| š¦ Build Scripts | Ready-to-use development and production scripts |
| š Production Ready | Optimized build configuration |
---
Run without any arguments to enter interactive mode:
`bash`
npx create-mcp-use-app
You'll be prompted for:
- Project name
- Project template
- Package manager preference
Specify the project name directly:
`bash`
npx create-mcp-use-app my-project
`bashUse a specific template
npx create-mcp-use-app my-project --template mcp-apps
npx create-mcp-use-app my-project --template mcp-ui
---
šØ Available Templates
$3
The starter template includes:
- Comprehensive MCP server setup with all features
- Example tool, resource, and prompt
- Both MCP-UI and OpenAI Apps SDK widget examples
- Full TypeScript configuration
- Development and production scripts
Perfect for getting started with all available features or building full-featured MCP servers.
$3
The mcp-apps template includes:
- MCP server setup focused on OpenAI Apps SDK integration
- OpenAI Apps SDK compatible widgets
- Example display-weather widget
- Optimized for OpenAI assistant integration
Ideal for building MCP servers that integrate with OpenAI's Apps SDK.
$3
The mcp-ui template includes:
- MCP server setup focused on MCP-UI resources
- Interactive UI components example
- Kanban board widget demonstration
- Clean, focused setup for UI-first applications
Best for building MCP servers with rich interactive UI components.
$3
You can use any GitHub repository as a template by providing the repository URL:
`bash
Short format (owner/repo)
npx create-mcp-use-app my-project --template owner/repoFull URL format
npx create-mcp-use-app my-project --template https://github.com/owner/repoWith specific branch
npx create-mcp-use-app my-project --template owner/repo#branch-name
npx create-mcp-use-app my-project --template https://github.com/owner/repo#branch-name
`The repository will be cloned and its contents will be used to initialize your project. This is useful for:
- Using community templates
- Sharing custom templates within your organization
- Creating projects from existing repositories
Note: Git must be installed and available in your PATH to use GitHub repository templates.
---
šļø What Gets Installed
The scaffolded project includes these dependencies:
$3
-
mcp-use - The MCP framework
- @mcp-use/cli - Build and development tool
- @mcp-use/inspector - Web-based debugger$3
-
typescript - TypeScript compiler
- tsx - TypeScript executor for development
- @types/node - Node.js type definitions$3
Different templates may include additional dependencies based on their features:
- UI libraries (React, styling frameworks)
- Widget-specific utilities
---
š After Installation
Once your project is created, you can:
$3
`bash
npm run dev
or
yarn dev
or
pnpm dev
`This will:
1. Start the MCP server on port 3000
2. Open the inspector in your browser
3. Watch for file changes and auto-reload
$3
`bash
npm run build
`Creates an optimized build in the
dist/ directory.$3
`bash
npm run start
`Runs the production build.
---
š” First Steps
After creating your app, here's what to do next:
$3
Open
src/index.ts to see how to:- Define MCP tools with Zod schemas
- Create resources for data access
- Set up prompts for AI interactions
$3
The inspector automatically opens at
http://localhost:3000/inspector where you can:- Test your tools interactively
- View available resources
- Debug tool executions
- Monitor server status
$3
Edit
resources/example-widget.tsx or create new widgets:`tsx
import React from "react";
import { useMcp } from "mcp-use/react";export default function MyWidget() {
const { callTool } = useMcp();
const handleClick = async () => {
const result = await callTool("my_tool", {
param: "value",
});
console.log(result);
};
return (
);
}
`$3
Use the MCP server with any MCP-compatible client:
`typescript
import { MCPClient, MCPAgent } from "mcp-use";
import { ChatOpenAI } from "@langchain/openai";const client = new MCPClient({
url: "http://localhost:3000/mcp",
});
const agent = new MCPAgent({
llm: new ChatOpenAI(),
client,
});
const result = await agent.run("Use my MCP tools");
`---
š§ Configuration
$3
The created project includes a
.env.example file:`bash
Server Configuration
PORT=3000
NODE_ENV=developmentOAuth (if using authentication)
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secretDatabase (if using database)
DATABASE_URL=postgresql://localhost/myappObservability (optional)
LANGFUSE_PUBLIC_KEY=your_public_key
LANGFUSE_SECRET_KEY=your_secret_key
`Copy to
.env and configure as needed:`bash
cp .env.example .env
`$3
The
tsconfig.json is pre-configured for MCP development:`json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"jsx": "react-jsx",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
}
}
`---
š Examples
$3
`typescript
server.tool("search_database", {
description: "Search for records in the database",
parameters: z.object({
query: z.string().describe("Search query"),
limit: z.number().optional().default(10),
}),
execute: async ({ query, limit }) => {
// Your tool logic here
const results = await db.search(query, limit);
return { results };
},
});
`$3
`typescript
server.resource("user_profile", {
description: "Current user profile data",
uri: "user://profile",
mimeType: "application/json",
fetch: async () => {
const profile = await getUserProfile();
return JSON.stringify(profile);
},
});
`$3
`typescript
server.prompt("code_review", {
description: "Review code for best practices",
arguments: [
{ name: "code", description: "Code to review", required: true },
{ name: "language", description: "Programming language", required: false },
],
render: async ({ code, language }) => {
return Please review this ${;
},
});
`---
š Troubleshooting
$3
Command not found:
`bash
Make sure you have Node.js 20.19+ installed
node --versionTry with npx
npx create-mcp-use-app@latest
`Permission denied:
`bash
On macOS/Linux, you might need sudo
sudo npx create-mcp-use-app my-app
`Network issues:
`bash
Use a different registry
npm config set registry https://registry.npmjs.org/
`Port already in use:
`bash
Change the port in your .env file
PORT=3001
``---
We welcome contributions! To contribute:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
See our contributing guide for more details.
---
- mcp-use Documentation
- Model Context Protocol Spec
- Creating MCP Tools
- Building UI Widgets
- Using the Inspector
- Supabase Edge Functions
---
MIT Ā© mcp-use