mcp-use CLI

🛠️ mcp-use CLI is a powerful build and development tool for creating MCP (Model Context Protocol) applications with integrated UI widgets. It enables developers to build MCP servers with custom React components that can be served alongside their MCP tools, providing rich visual interfaces for AI interactions.

📦 Related Packages

| Package | Description | Version |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| mcp-use | Core MCP framework |  |
| @mcp-use/inspector | Web-based MCP inspector |  |
| create-mcp-use-app | Create MCP apps |  |

---

✨ Key Features

| Feature | Description |
| ------------------------ | ------------------------------------------------------------------------------------ |
| 🚀 Auto Inspector | Automatically opens the MCP Inspector in your browser when development server starts |
| ♻️ Hot Reload | Development mode with automatic reloading for both server code and UI widgets |
| 🎨 Widget Builder | Compiles React components into standalone HTML pages with all dependencies bundled |
| 📦 Production Ready | Optimized production builds with hashed assets for caching |
| 🛠️ TypeScript First | Full TypeScript support with watch mode compilation |
| 🖥️ Multi-Environment | Separate commands for development, build, and production deployment |

---

🚀 Installation

``bash


Install globally

`bash
mcp-use dev [options]
`

What happens in dev mode:

1. TypeScript files are compiled in watch mode
2. UI widgets are built with hot reload
3. Server runs with auto-restart on changes (via tsx)
4. Inspector automatically opens in your browser at http://localhost:3000/inspector
5. MCP endpoint is available at http://localhost:3000/mcp

Options:

- -p, --path - Project directory (default: current directory)
- --port - Server port (default: 3000)
- --no-open - Don't auto-open inspector in browser

$3

Build your MCP application for production deployment:

`bash
mcp-use build [options]
`

What happens during build:

1. TypeScript is compiled to JavaScript
2. All .tsx files in resources/ are bundled as standalone HTML pages
3. Assets are hashed for optimal caching
4. Output is optimized and minified

Options:

- -p, --path - Project directory (default: current directory)

$3

Start the production server from built files:

`bash
mcp-use start [options]
`

Options:

- -p, --path - Project directory (default: current directory)
- --port - Server port (default: 3000)

$3

Deploy your MCP server to mcp-use cloud:

`bash


Login to mcp-use cloud

- --name - Custom deployment name
- --port - Server port (default: 3000)
- --runtime - Runtime environment: "node" or "python"
- --open - Open deployment in browser after success

Example:

`bash


Basic deployment

`bash


Create a new MCP app (using create-mcp-use-app)

`bash


Development on port 8080

`bash


Specify custom project path

`bash


In your CI/CD pipeline

`
my-mcp-app/
├── package.json
├── tsconfig.json
├── src/
│ └── index.ts # Your MCP server entry point
├── resources/ # UI widgets (React components)
│ ├── todo-list.tsx # Becomes /widgets/todo-list/index.html
│ └── dashboard.tsx # Becomes /widgets/dashboard/index.html
└── dist/ # Build output
├── index.js # Compiled server
└── resources/
└── mcp-use/
└── widgets/
├── todo-list/
│ ├── index.html
│ └── assets/
│ └── index-[hash].js
└── dashboard/
├── index.html
└── assets/
└── index-[hash].js
`

---

🎨 Creating UI Widgets

UI widgets are React components that get compiled into standalone HTML pages. They can interact with your MCP server tools using the useMcp hook:

`tsx
// resources/task-manager.tsx
import React, { useState, useEffect } from "react";
import { useMcp } from "mcp-use/react";

export default function TaskManager() {
const { callTool, status, error } = useMcp();
const [tasks, setTasks] = useState([]);
const [newTask, setNewTask] = useState("");

useEffect(() => {
loadTasks();
}, []);

const loadTasks = async () => {
const result = await callTool("list_tasks");
setTasks(result.tasks);
};

const addTask = async () => {
if (!newTask.trim()) return;

await callTool("create_task", {
title: newTask,
status: "pending",
});

setNewTask("");
await loadTasks();
};

if (status === "connecting") return

This widget will be available at http://localhost:3000/widgets/task-manager after building.

---

🔧 Configuration

$3

Ensure your tsconfig.json includes:

`json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"jsx": "react-jsx",
"esModuleInterop": true,
"skipLibCheck": true,
"strict": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src//", "resources//"]
}
`

$3

Add these scripts for convenience:

`json
{
"scripts": {
"dev": "mcp-use dev",
"build": "mcp-use build",
"start": "mcp-use start",
"serve": "npm run build && npm run start"
}
}
`

---

🚀 Advanced Usage

$3

#### Development & Build

`bash


Custom port via environment variable

`bash


Frontend URL (where /auth/cli page is)

`dockerfile


Dockerfile

`ts
import express from "express";
import path from "path";

const app = express();

// Serve MCP widgets
app.use(
"/widgets",
express.static(path.join(__dirname, "../dist/resources/mcp-use/widgets"))
);

// Your other routes...
`

---

🐛 Troubleshooting

$3

Port already in use:

`bash


Use a different port

`bash


Check your tsconfig.json

- Ensure .tsx files are in the resources/ directory
- Check that React dependencies are installed
- Verify the build output in dist/resources/mcp-use/widgets/

Inspector not opening:

`bash


Manually open http://localhost:3000/inspector

---

📚 Learn More

- mcp-use Documentation
- Model Context Protocol
- Creating MCP Servers
- MCP Inspector Guide

---

📜 License

MIT © mcp-use