mirror of
https://github.com/mcp-use/mcp-use.git
synced 2026-09-14 18:06:01 +08:00
docs: redesign v2 README for humans and agents (#2030)
* docs: redesign v2 README for humans and agents * docs: simplify agent prompt and add product screenshots * docs: zoom out Inspector screenshot * docs: add framework comparison section * docs: use black comparison highlights * docs: link self-hosting deployment guide * docs: clarify official SDK relationship * docs: simplify self-hosting comparison * docs: publish v2 benchmark report * docs: keep benchmark report in repository * docs: keep readme proposal self-contained * docs: simplify scaffold command * docs: use mcp-use agent prompt URL * docs: refine benchmark comparisons * docs: add MCP App product captures * docs: refine TypeScript benchmark comparison * docs: add framework comparison matrix * docs: expand framework comparison data * docs: compare OAuth adapter support * docs: simplify framework comparison * docs: highlight integrated verification * docs: render comparison as colored grid * docs: compare equivalent MCP stacks * docs: compare unpacked npm footprint * docs: compare installed package counts * docs: clarify framework comparison support * docs: clarify official SDK comparison stack * docs: simplify framework comparison * docs: streamline v2 README experience * docs: reframe ChatGPT app screenshot * docs: capture yellow app gradient * docs: show ChatGPT navigation in app screenshot * docs: restore mcp-use wordmark * docs: sharpen MCP framework positioning * docs: refine README onboarding copy * docs: update Manufact dashboard preview * docs: simplify Manufact deployment section * docs: add Inspector tunneling workflow * docs: add v1 migration path * docs: refine top-level onboarding layout * docs: expand Get started table * docs: fill Get started layout * docs: balance onboarding columns * docs: keep header badges inline
This commit is contained in:
Enrico Toniato
@@ -1,114 +1,110 @@
|
||||
<div align="center">
|
||||
<div align="center">
|
||||
<a href="https://mcp-use.com">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="./static/logo_white.svg">
|
||||
<source media="(prefers-color-scheme: light)" srcset="./static/logo_black.svg">
|
||||
<img alt="mcp use logo" src="./static/logo_black.svg" width="60%" >
|
||||
<source media="(prefers-color-scheme: dark)" srcset="./docs/logo/dark.svg">
|
||||
<img alt="mcp-use" src="./docs/logo/light.svg" width="60%">
|
||||
</picture>
|
||||
</a>
|
||||
</div>
|
||||
|
||||
|
||||
<p align="center">
|
||||
<a href="https://mcp-use.com/docs" alt="Documentation">
|
||||
<img src="https://img.shields.io/badge/mcp--use-docs-blue?labelColor=white" /></a>
|
||||
<a href="https://manufact.com" alt="Website">
|
||||
<img src="https://img.shields.io/badge/made by-manufact.com-blue" /></a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/blob/main/LICENSE" alt="License">
|
||||
<img src="https://img.shields.io/github/license/mcp-use/mcp-use" /></a>
|
||||
<a href="https://discord.gg/XkNkSkMz3V" alt="Discord">
|
||||
<img src="https://dcbadge.limes.pink/api/server/XkNkSkMz3V?style=flat" /></a>
|
||||
<br/>
|
||||
<a href="https://mcp-use.com/docs/python" alt="Python docs">
|
||||
<img src="https://img.shields.io/badge/python-docs-blue?labelColor=white&logo=python" alt="Badge"></a>
|
||||
<a href="https://pypi.org/project/mcp_use/" alt="PyPI Version">
|
||||
<img src="https://img.shields.io/pypi/v/mcp_use.svg"/></a>
|
||||
<a href="https://pypi.org/project/mcp_use/" alt="PyPI Downloads">
|
||||
<img src="https://static.pepy.tech/badge/mcp-use" /></a>
|
||||
<br/>
|
||||
<a href="https://mcp-use.com/docs/typescript" alt="Typescript Documentation">
|
||||
<img src="https://img.shields.io/badge/typescript-docs-blue?labelColor=white&logo=typescript" alt="Badge"></a>
|
||||
<a href="https://www.npmjs.com/package/mcp-use" alt="NPM Version">
|
||||
<img src="https://img.shields.io/npm/v/mcp-use.svg"/></a>
|
||||
<a href="https://www.npmjs.com/package/mcp-use" alt="NPM Downloads">
|
||||
<img src="https://img.shields.io/npm/dw/mcp-use.svg"/></a>
|
||||
<br/>
|
||||
</p>
|
||||
<h1>The TypeScript framework for MCP.</h1>
|
||||
|
||||
<p>
|
||||
Build, test, and ship MCP servers, ChatGPT plugins, Claude connectors, and interactive apps with typed tools, native Views, and a built-in Inspector.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<a href="https://mcp-use.com/docs/typescript/getting-started/quickstart"><strong>Documentation</strong></a>
|
||||
· <a href="https://inspector.mcp-use.com/inspector"><strong>Inspector</strong></a>
|
||||
· <a href="#examples"><strong>Examples</strong></a>
|
||||
· <a href="https://manufact.com"><strong>Deploy</strong></a>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<a href="https://www.npmjs.com/package/mcp-use">
|
||||
<img src="https://img.shields.io/npm/v/mcp-use/beta.svg?label=v2%20beta" alt="mcp-use v2 beta">
|
||||
</a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/blob/main/LICENSE">
|
||||
<img src="https://img.shields.io/github/license/mcp-use/mcp-use" alt="MIT license">
|
||||
</a>
|
||||
<a href="https://discord.gg/XkNkSkMz3V">
|
||||
<img src="https://dcbadge.limes.pink/api/server/XkNkSkMz3V?style=flat&compact=true" alt="Discord">
|
||||
</a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
## About
|
||||
|
||||
<b>mcp-use</b> is the fullstack MCP framework
|
||||
to build MCP Apps for ChatGPT / Claude & MCP Servers for AI Agents.
|
||||
|
||||
- **Build** with mcp-use SDK ([ts](https://www.npmjs.com/package/mcp-use) | [py](https://pypi.org/project/mcp_use/)): MCP Servers and MCP Apps
|
||||
- **Preview** on mcp-use MCP Inspector ([online](https://inspector.mcp-use.com/inspector) | [oss](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/inspector)): Test and debug your MCP Servers and Apps
|
||||
- **Deploy** on [Manufact MCP Cloud](https://manufact.com): Connect your GitHub repo and have your MCP Server and App up and running in production with observability, metrics, logs, branch-deployments, and more
|
||||
|
||||
## Documentation
|
||||
|
||||
Visit our [docs](https://mcp-use.com/docs) or jump to a quickstart ([TypeScript](https://mcp-use.com/docs/typescript/getting-started/quickstart) | [Python](https://mcp-use.com/docs/python/getting-started/quickstart))
|
||||
|
||||
### V2 TypeScript beta
|
||||
|
||||
V2 prereleases are published from reviewed pull requests merged into the `beta` branch, using GitHub OIDC trusted publishing. They use npm's `beta` dist tag and do not change `latest` or `canary`.
|
||||
|
||||
```bash
|
||||
npm install mcp-use@beta @mcp-use/client@beta @mcp-use/agent@beta
|
||||
npm install @mcp-use/cli@beta @mcp-use/inspector@beta
|
||||
npm create mcp-use-app@beta
|
||||
```
|
||||
|
||||
### Skills for Coding Agents
|
||||
|
||||
> **Using Claude Code, Codex, Cursor or other AI coding agents?**
|
||||
> [!NOTE]
|
||||
> **TypeScript v2 is in beta.** Use the npm `beta` channel with Node.js **22.22.2 or newer**. [Python and TypeScript v1 →](#ecosystem)
|
||||
>
|
||||
> **[Install mcp-use skill for MCP Apps](https://skills.sh/mcp-use/mcp-use/mcp-apps-builder)**
|
||||
> **Migrating from v1?** Most existing v1 servers can upgrade to `mcp-use@beta` without code changes through the included compatibility layer. To get the full benefits of v2, we recommend migrating to the native v2 API.
|
||||
>
|
||||
> **Give it to your agent:**
|
||||
>
|
||||
> ```text
|
||||
> Migrate this mcp-use project to v2 following
|
||||
> https://docs.mcp-use.com/v2/server/migration
|
||||
> ```
|
||||
>
|
||||
> [Read the migration guide →](https://docs.mcp-use.com/v2/server/migration)
|
||||
|
||||
## Quickstart: MCP Servers and MCP Apps
|
||||
## Get started
|
||||
|
||||
### <img src="./static/typescript.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> TypeScript
|
||||
<table width="100%" style="width: 100%; table-layout: fixed;">
|
||||
<colgroup>
|
||||
<col width="50%">
|
||||
<col width="50%">
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr>
|
||||
<th width="50%">Start with code</th>
|
||||
<th width="50%">Start with your agent</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td width="50%" valign="top">
|
||||
<pre lang="bash"><code>npx -y create-mcp-use-app@beta # create an MCP app</code></pre>
|
||||
<p>Run <code>npm run dev</code> in the generated project.</p>
|
||||
<p>Open <a href="http://localhost:3000/mcp/inspector"><code>http://localhost:3000/mcp/inspector</code></a></p>
|
||||
<p><a href="https://mcp-use.com/docs/typescript/getting-started/quickstart">TS Docs</a></p>
|
||||
</td>
|
||||
<td width="50%" valign="top">
|
||||
<pre lang="text"><code>Build an MCP server: https://mcp-use.com/prompt.md</code></pre>
|
||||
<p><a href="https://mcp-use.com/prompt.md">Read the prompt →</a></p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Build your first MCP Server or MPC App:
|
||||
## Everything you need to ship MCP
|
||||
|
||||
```bash
|
||||
npx create-mcp-use-app@latest
|
||||
```
|
||||
<table>
|
||||
<tr>
|
||||
<td width="50%" valign="top">
|
||||
<h3>Fully typed</h3>
|
||||
<p>Zod schemas flow from tools to structured results, View props, and tool calls.</p>
|
||||
</td>
|
||||
<td width="50%" valign="top">
|
||||
<h3>Native Views</h3>
|
||||
<p>Bind React Views directly to tools and ship interactive apps without custom extension wiring.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%" valign="top">
|
||||
<h3>Agent-first and headless</h3>
|
||||
<p>Scaffold, invoke, inspect, screenshot, and deploy through your agent.</p>
|
||||
</td>
|
||||
<td width="50%" valign="top">
|
||||
<h3>Built-in debugging tools</h3>
|
||||
<p>Inspect tools and Views in the browser or headlessly through the CLI.</p>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
Or create a server manually:
|
||||
## Quickstart
|
||||
|
||||
```typescript
|
||||
import { MCPServer, text } from "mcp-use/server";
|
||||
import { z } from "zod";
|
||||
The scaffold gives you the server, TypeScript configuration, development scripts, Inspector, and a React view pipeline. Start it once and the MCP endpoint also serves a client-ready landing page with its connection URL and setup instructions.
|
||||
|
||||
const server = new MCPServer({
|
||||
name: "my-server",
|
||||
version: "1.0.0",
|
||||
});
|
||||
|
||||
export const getWeather = server.tool(
|
||||
{
|
||||
name: "get_weather",
|
||||
description: "Get weather for a city",
|
||||
schema: z.object({ city: z.string() }),
|
||||
},
|
||||
async ({ city }) => {
|
||||
return text(`Temperature: 72°F, Condition: sunny, City: ${city}`);
|
||||
},
|
||||
);
|
||||
|
||||
await server.listen(3000);
|
||||
// MCP endpoint at http://localhost:3000/mcp
|
||||
```
|
||||
|
||||
[**→ Full TypeScript Server Documentation**](https://mcp-use.com/docs/typescript/server)
|
||||
|
||||
## MCP Apps
|
||||
|
||||
MCP Apps let you build interactive views that work across Claude, ChatGPT, and other MCP clients.
|
||||
|
||||
**Server**: bind a tool to a view and return its structured output:
|
||||
Replace its `index.ts` with a view-bound tool like this:
|
||||
|
||||
```typescript
|
||||
import { MCPServer } from "mcp-use";
|
||||
@@ -116,397 +112,258 @@ import { z } from "zod";
|
||||
|
||||
const server = new MCPServer({
|
||||
name: "weather-app",
|
||||
title: "Weather App",
|
||||
version: "1.0.0",
|
||||
});
|
||||
|
||||
const weatherInput = z.object({
|
||||
city: z.string().describe("City to look up"),
|
||||
});
|
||||
|
||||
const weatherOutput = z.object({
|
||||
city: z.string(),
|
||||
temperature: z.number(),
|
||||
conditions: z.string(),
|
||||
});
|
||||
|
||||
export const getWeather = server.tool(
|
||||
{
|
||||
name: "get-weather",
|
||||
description: "Get weather for a city",
|
||||
inputSchema: z.object({ city: z.string() }),
|
||||
outputSchema: z.object({
|
||||
city: z.string(),
|
||||
temperature: z.number(),
|
||||
conditions: z.string(),
|
||||
}),
|
||||
view: { name: "weather-display" },
|
||||
title: "Get weather",
|
||||
description: "Get the current weather for a city",
|
||||
inputSchema: weatherInput,
|
||||
outputSchema: weatherOutput,
|
||||
view: { name: "weather-card" },
|
||||
annotations: {
|
||||
readOnlyHint: true,
|
||||
destructiveHint: false,
|
||||
openWorldHint: true,
|
||||
},
|
||||
},
|
||||
async ({ city }) => {
|
||||
const weather = { city, temperature: 22, conditions: "Sunny" };
|
||||
const weather = {
|
||||
city,
|
||||
temperature: 22,
|
||||
conditions: "Sunny",
|
||||
};
|
||||
|
||||
return {
|
||||
content: [
|
||||
{ type: "text", text: `Weather in ${city}: Sunny, 22°C` },
|
||||
{
|
||||
type: "text",
|
||||
text: `Weather in ${city}: ${weather.conditions}, ${weather.temperature}°C`,
|
||||
},
|
||||
],
|
||||
structuredContent: weather,
|
||||
};
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
export default server;
|
||||
```
|
||||
|
||||
**View**: create the React component in `views/weather-display/view.tsx`:
|
||||
[Explore MCP server tools →](https://mcp-use.com/docs/typescript/server/tools)
|
||||
|
||||
## Add Views to your tools
|
||||
|
||||
Create `views/weather-card/view.tsx`. The directory name matches `view.name` on the tool:
|
||||
|
||||
```tsx
|
||||
import { useToolContext, useViewTheme } from "mcp-use/react";
|
||||
import { useCallTool, useToolContext } from "mcp-use/react";
|
||||
|
||||
interface WeatherOutput {
|
||||
city: string;
|
||||
temperature: number;
|
||||
conditions: string;
|
||||
}
|
||||
export default function WeatherCard() {
|
||||
const { status, toolOutput, toolInput } =
|
||||
useToolContext<"get-weather">();
|
||||
const refresh = useCallTool("get-weather");
|
||||
|
||||
export default function WeatherDisplay() {
|
||||
const view = useToolContext();
|
||||
const theme = useViewTheme();
|
||||
const isDark = theme === "dark";
|
||||
if (status === "pending") {
|
||||
return <p>Checking the weather in {toolInput?.city ?? "your city"}…</p>;
|
||||
}
|
||||
if (status === "error") return <p>Could not load the weather.</p>;
|
||||
|
||||
if (view.status === "pending") return <div>Loading...</div>;
|
||||
if (view.status === "error") return <div>{view.error.message}</div>;
|
||||
|
||||
const weather = view.toolOutput as WeatherOutput;
|
||||
const weather = refresh.data?.structuredContent ?? toolOutput;
|
||||
|
||||
return (
|
||||
<div
|
||||
style={{
|
||||
background: isDark ? "#1a1a2e" : "#f0f4ff",
|
||||
borderRadius: 16,
|
||||
padding: 24,
|
||||
}}
|
||||
>
|
||||
<main style={{ padding: 24 }}>
|
||||
<h2>{weather.city}</h2>
|
||||
<p>
|
||||
{weather.temperature}° — {weather.conditions}
|
||||
{weather.temperature}°C · {weather.conditions}
|
||||
</p>
|
||||
</div>
|
||||
<button
|
||||
disabled={refresh.isPending}
|
||||
onClick={() => void refresh.callTool({ city: weather.city })}
|
||||
>
|
||||
{refresh.isPending ? "Refreshing…" : "Refresh"}
|
||||
</button>
|
||||
{refresh.error && <p>{refresh.error.message}</p>}
|
||||
</main>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Views under `views/<name>/view.tsx` are discovered by `mcp-use dev` and
|
||||
`mcp-use build`. The tool's `view.name` binds the result to that view.
|
||||
<p align="center">
|
||||
<img src="./static/readme/chatgpt-hello-world.jpg" alt="Hello World MCP App rendered in a ChatGPT conversation" width="100%" />
|
||||
<br />
|
||||
<sub>Build interactive UI experiences within ChatGPT with mcp-use.</sub>
|
||||
</p>
|
||||
|
||||
Visit [**MCP Apps Documentation**](https://mcp-use.com/docs/typescript/server/mcp-apps)
|
||||
[Build your first MCP App →](https://mcp-use.com/docs/typescript/mcp-apps/quickstart)
|
||||
|
||||
## Templates
|
||||
## Build
|
||||
|
||||
Ready-to-use MCP Apps you can deploy in one click or remix as your own.
|
||||
|
||||
| Preview | Name | Tools | Demo URL | Repo | Deploy |
|
||||
| ------------------------------------------------------------------------------------------------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
|  | Chart Builder | `create-chart` | [Open URL](https://yellow-shadow-21833.run.mcp-use.com/mcp) | [mcp-use/mcp-chart-builder](https://github.com/mcp-use/mcp-chart-builder) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-chart-builder&branch=main&project-name=mcp-chart-builder&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Diagram Builder | `create-diagram`, `edit-diagram` | [Open URL](https://lucky-darkness-402ph.run.mcp-use.com/mcp) | [mcp-use/mcp-diagram-builder](https://github.com/mcp-use/mcp-diagram-builder) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-diagram-builder&branch=main&project-name=mcp-diagram-builder&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Slide Deck | `create-slides`, `edit-slide` | [Open URL](https://solitary-block-r6m6x.run.mcp-use.com/mcp) | [mcp-use/mcp-slide-deck](https://github.com/mcp-use/mcp-slide-deck) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-slide-deck&branch=main&project-name=mcp-slide-deck&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Maps Explorer | `show-map`, `get-place-details`, `add-markers` | [Open URL](https://super-night-ttde2.run.mcp-use.com/mcp) | [mcp-use/mcp-maps-explorer](https://github.com/mcp-use/mcp-maps-explorer) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-maps-explorer&branch=main&project-name=mcp-maps-explorer&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Hugging Face Spaces | `search-spaces`, `show-space`, `trending-spaces` | [Open URL](https://gentle-frost-pvxpk.run.mcp-use.com/mcp) | [mcp-use/mcp-huggingface-spaces](https://github.com/mcp-use/mcp-huggingface-spaces) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-huggingface-spaces&branch=main&project-name=mcp-huggingface-spaces&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Recipe Finder | `search-recipes`, `get-recipe`, `meal-plan`, `recipe-suggestion` | [Open URL](https://bold-tree-1fe79.run.mcp-use.com/mcp) | [mcp-use/mcp-recipe-finder](https://github.com/mcp-use/mcp-recipe-finder) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-recipe-finder&branch=main&project-name=mcp-recipe-finder&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Widget Gallery | `show-react-widget`, `html-greeting`, `mcp-ui-poll`, `programmatic-counter`, `detect-client` | [Open URL](https://wandering-lake-mmxhs.run.mcp-use.com/mcp) | [mcp-use/mcp-widget-gallery](https://github.com/mcp-use/mcp-widget-gallery) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-widget-gallery&branch=main&project-name=mcp-widget-gallery&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Multi Server Hub | `hub-status`, `hub-config-example`, `audit-log` | [Open URL](https://soft-voice-4nxfi.run.mcp-use.com/mcp) | [mcp-use/mcp-multi-server-hub](https://github.com/mcp-use/mcp-multi-server-hub) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-multi-server-hub&branch=main&project-name=mcp-multi-server-hub&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | File Manager | `open-vault`, `get-file`, `list-files` | [Open URL](https://muddy-pond-eyays.run.mcp-use.com/mcp) | [mcp-use/mcp-file-manager](https://github.com/mcp-use/mcp-file-manager) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-file-manager&branch=main&project-name=mcp-file-manager&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Progress Demo | `process-data`, `fetch-report`, `delete-dataset`, `search-external`, `failing-tool` | [Open URL](https://crimson-river-pzsz1.run.mcp-use.com/mcp) | [mcp-use/mcp-progress-demo](https://github.com/mcp-use/mcp-progress-demo) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-progress-demo&branch=main&project-name=mcp-progress-demo&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | i18n Adaptive | `show-context`, `detect-caller` | [Open URL](https://falling-grass-58yov.run.mcp-use.com/mcp) | [mcp-use/mcp-i18n-adaptive](https://github.com/mcp-use/mcp-i18n-adaptive) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-i18n-adaptive&branch=main&project-name=mcp-i18n-adaptive&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Media Mixer | `generate-image`, `generate-audio`, `generate-pdf`, `get-report`, `get-html-snippet`, `get-xml-config`, `get-stylesheet`, `get-script`, `get-data-array` | [Open URL](https://wandering-breeze-nuipu.run.mcp-use.com/mcp) | [mcp-use/mcp-media-mixer](https://github.com/mcp-use/mcp-media-mixer) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-media-mixer&branch=main&project-name=mcp-media-mixer&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|  | Resource Watcher | `show-config`, `update-config`, `toggle-feature`, `list-roots` | [Open URL](https://fragrant-term-zmdks.run.mcp-use.com/mcp) | [mcp-use/mcp-resource-watcher](https://github.com/mcp-use/mcp-resource-watcher) | [](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-resource-watcher&branch=main&project-name=mcp-resource-watcher&port=3000&runtime=node&base-image=node%3A22) |
|
||||
|
||||
---
|
||||
|
||||
### <img src="./static/python.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> Python
|
||||
Create the production build:
|
||||
|
||||
```bash
|
||||
pip install mcp-use
|
||||
npm run build
|
||||
```
|
||||
|
||||
```python
|
||||
from typing import Annotated
|
||||
## Inspect
|
||||
|
||||
from mcp.types import ToolAnnotations
|
||||
from pydantic import Field
|
||||
|
||||
from mcp_use import MCPServer
|
||||
|
||||
server = MCPServer(name="Weather Server", version="1.0.0")
|
||||
|
||||
@server.tool(
|
||||
name="get_weather",
|
||||
description="Get current weather information for a location",
|
||||
annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
|
||||
)
|
||||
async def get_weather(
|
||||
city: Annotated[str, Field(description="City name")],
|
||||
) -> str:
|
||||
return f"Temperature: 72°F, Condition: sunny, City: {city}"
|
||||
|
||||
# Start server with auto-inspector
|
||||
server.run(transport="streamable-http", port=8000)
|
||||
# 🎉 Inspector at http://localhost:8000/inspector
|
||||
```
|
||||
|
||||
[**→ Full Python Server Documentation**](https://mcp-use.com/docs/python/server/index)
|
||||
|
||||
---
|
||||
|
||||
## Inspector
|
||||
|
||||
The mcp-use Inspector lets you test and debug your MCP servers interactively.
|
||||
|
||||
**Auto-mounted in local development** when `@mcp-use/inspector` is installed as a dev dependency:
|
||||
Start development mode to serve the MCP endpoint at [`http://localhost:3000/mcp`](http://localhost:3000/mcp). The Inspector is automatically available at [`http://localhost:3000/mcp/inspector`](http://localhost:3000/mcp/inspector):
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
# Inspector at http://localhost:3000/mcp/inspector
|
||||
```
|
||||
|
||||
Production `server.listen()` and `mcp-use start` expose only the MCP server, not the Inspector.
|
||||
<p align="center">
|
||||
<img src="./static/readme/inspector-hello-world.jpg" alt="Hello World MCP App rendered in the mcp-use Inspector" width="100%" />
|
||||
<br />
|
||||
<sub>Invoke tools, validate inputs, and inspect interactive Views in the same development loop.</sub>
|
||||
</p>
|
||||
|
||||
**Online** when connecting to hosted MCP servers:
|
||||
<br>
|
||||
Start a tunnel from the Inspector UI or run `mcp-use dev --tunnel` to get a public URL for your local MCP server and test it with ChatGPT and Claude before deployment. [Learn more about tunneling →](https://docs.mcp-use.com/tunneling)
|
||||
|
||||
> Visit https://inspector.mcp-use.com
|
||||
|
||||
**Standalone**: inspect any MCP server:
|
||||
Inspect the same server headlessly from the terminal, invoke representative tools, and capture a View screenshot:
|
||||
|
||||
```bash
|
||||
npx @mcp-use/inspector --url http://localhost:3000/mcp
|
||||
npm install --save-dev @mcp-use/client@beta
|
||||
npx mcp-use client connect local http://localhost:3000/mcp
|
||||
npx mcp-use client local tools list
|
||||
npx mcp-use client local tools call get-weather city=Tokyo
|
||||
npx mcp-use screenshot \
|
||||
--server local \
|
||||
--tool get-weather \
|
||||
city=Tokyo \
|
||||
--output weather-card.png
|
||||
```
|
||||
|
||||
Visit [**Inspector Documentation**](https://mcp-use.com/docs/inspector/index)
|
||||
|
||||
---
|
||||
|
||||
## Deploy
|
||||
|
||||
Deploy your MCP server to production:
|
||||
Ship to [Manufact](https://manufact.com) and get observability, analytics, evals, submission readiness, and Git-based preview environments for free.
|
||||
|
||||
```bash
|
||||
npx @mcp-use/cli login
|
||||
npx @mcp-use/cli deploy
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
Or connect your GitHub repo on [manufact.com](https://manufact.com) — production-ready with observability, metrics, logs, and branch-deployments.
|
||||
Prefer to run it yourself? Follow the [self-hosting guide →](https://mcpuse-codex-v1-v2-docs-split.mintlify.site/v2/typescript/server/deployment/runtime-patterns).
|
||||
|
||||
---
|
||||
## How mcp-use compares
|
||||
|
||||
## Package Overview
|
||||
mcp-use builds on the official TypeScript SDK v2 and adds first-class Views, typed tool-to-UI contracts, an optimized stateless runtime, the Inspector, screenshot verification, agent-first CLI workflows, and deployment.
|
||||
|
||||
This monorepo contains multiple packages for both Python and TypeScript:
|
||||
In our benchmark, mcp-use v2 reached **10,982 median operations per second** and used **74.4 MiB across 51 installed packages**.
|
||||
|
||||
### Python Packages
|
||||
```mermaid
|
||||
block-beta
|
||||
columns 6
|
||||
|
||||
| Package | Description | Version |
|
||||
| ----------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| **mcp-use** | Complete MCP server and MCP agent SDK | [](https://pypi.org/project/mcp_use/) |
|
||||
metric["Metric"] mcp["mcp-use v2"] official["Official SDK v2*"] xmcp["xmcp"] skybridge["Skybridge"] handler["mcp-handler"]
|
||||
|
||||
### TypeScript Packages
|
||||
speed["Speed"] speedMcp["10,982 ops/s"] speedOfficial["8,050 ops/s"] speedXmcp["6,585 ops/s"] speedSkybridge["8,116 ops/s"] speedHandler["6,324 ops/s"]
|
||||
install["Clean install"] installMcp["74.4 MiB"] installOfficial["99.0 MiB"] installXmcp["121.9 MiB"] installSkybridge["137.5 MiB"] installHandler["388.0 MiB"]
|
||||
packages["Installed<br/>packages"] packagesMcp["51"] packagesOfficial["119"] packagesXmcp["171"] packagesSkybridge["300"] packagesHandler["130"]
|
||||
views["Views"] viewsMcp["✅"] viewsOfficial["◐ Extension"] viewsXmcp["✅"] viewsSkybridge["✅"] viewsHandler["❌"]
|
||||
nativeViews["Native Views<br/>on MCP 2026"] nativeViewsMcp["✅"] nativeViewsOfficial["❌"] nativeViewsXmcp["❌"] nativeViewsSkybridge["❌"] nativeViewsHandler["❌"]
|
||||
oauth["One-line<br/>OAuth adapters"] oauthMcp["✅"] oauthOfficial["◐ Primitives"] oauthXmcp["✅"] oauthSkybridge["✅"] oauthHandler["❌"]
|
||||
protocol["MCP 2026<br/>protocol"] protocolMcp["✅"] protocolOfficial["✅"] protocolXmcp["❌"] protocolSkybridge["❌"] protocolHandler["❌"]
|
||||
screenshot["Built-in View<br/>screenshot CLI"] screenshotMcp["✅"] screenshotOfficial["❌"] screenshotXmcp["❌"] screenshotSkybridge["❌"] screenshotHandler["❌"]
|
||||
tunnel["Built-in<br/>tunneling"] tunnelMcp["✅"] tunnelOfficial["❌"] tunnelXmcp["❌"] tunnelSkybridge["✅"] tunnelHandler["❌"]
|
||||
inspector["Built-in<br/>Inspector"] inspectorMcp["✅"] inspectorOfficial["❌"] inspectorXmcp["❌"] inspectorSkybridge["◐ Limited"] inspectorHandler["❌"]
|
||||
|
||||
| Package | Description | Version |
|
||||
| ---------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| **mcp-use** | Core framework for MCP servers, MCP apps, and MCP agents | [](https://www.npmjs.com/package/mcp-use) |
|
||||
| **@mcp-use/cli** | Build tool with hot reload and auto-inspector | [](https://www.npmjs.com/package/@mcp-use/cli) |
|
||||
| **@mcp-use/inspector** | Web-based previewer and debugger for MCP servers | [](https://www.npmjs.com/package/@mcp-use/inspector) |
|
||||
| **create-mcp-use-app** | Project scaffolding tool | [](https://www.npmjs.com/package/create-mcp-use-app) |
|
||||
classDef label fill:#f6f8fa,stroke:#d0d7de,color:#1f2328,font-weight:bold
|
||||
classDef brand fill:#dcfce7,stroke:#16a34a,color:#166534,font-weight:bold
|
||||
classDef header fill:#f6f8fa,stroke:#d0d7de,color:#1f2328,font-weight:bold
|
||||
classDef value fill:#ffffff,stroke:#d0d7de,color:#1f2328
|
||||
classDef leader fill:#dcfce7,stroke:#16a34a,color:#166534,font-weight:bold
|
||||
classDef partial fill:#fff8c5,stroke:#d4a72c,color:#633c01,font-weight:bold
|
||||
classDef unavailable fill:#f6f8fa,stroke:#d0d7de,color:#6e7781
|
||||
|
||||
---
|
||||
|
||||
## Also: MCP Agent & Client
|
||||
|
||||
mcp-use also provides a full MCP Agent and Client implementation.
|
||||
|
||||
<details>
|
||||
<summary>Build an AI Agent</summary>
|
||||
|
||||
### <img src="./static/python.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> Python
|
||||
|
||||
```bash
|
||||
pip install mcp-use langchain-openai
|
||||
class metric,speed,install,packages,views,nativeViews,oauth,protocol,screenshot,tunnel,inspector label
|
||||
class mcp brand
|
||||
class official,xmcp,skybridge,handler header
|
||||
class speedOfficial,speedXmcp,speedSkybridge,speedHandler,installOfficial,installXmcp,installSkybridge,installHandler,packagesOfficial,packagesXmcp,packagesSkybridge,packagesHandler value
|
||||
class speedMcp,installMcp,packagesMcp,viewsMcp,viewsXmcp,viewsSkybridge,nativeViewsMcp,oauthMcp,oauthXmcp,oauthSkybridge,protocolMcp,protocolOfficial,screenshotMcp,tunnelMcp,tunnelSkybridge,inspectorMcp leader
|
||||
class viewsOfficial,oauthOfficial,inspectorSkybridge partial
|
||||
class viewsHandler,nativeViewsOfficial,nativeViewsXmcp,nativeViewsSkybridge,nativeViewsHandler,oauthHandler,protocolXmcp,protocolSkybridge,protocolHandler,screenshotOfficial,screenshotXmcp,screenshotSkybridge,screenshotHandler,tunnelOfficial,tunnelXmcp,tunnelHandler,inspectorOfficial,inspectorXmcp,inspectorHandler unavailable
|
||||
```
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from langchain_openai import ChatOpenAI
|
||||
from mcp_use import MCPAgent, MCPClient
|
||||
<sub>* Includes `@modelcontextprotocol/ext-apps`, Vite, and zod for an MCP Apps-capable stack.</sub>
|
||||
|
||||
async def main():
|
||||
config = {
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
**[Read the detailed benchmark report →](./benchmark.md)**
|
||||
|
||||
client = MCPClient.from_dict(config)
|
||||
llm = ChatOpenAI(model="gpt-4o")
|
||||
agent = MCPAgent(llm=llm, client=client)
|
||||
**Does mcp-use lock deployment to Manufact Cloud?**
|
||||
|
||||
result = await agent.run("List all files in the directory")
|
||||
print(result)
|
||||
No. Manufact Cloud is the managed path for deployment, analytics, evals, observability, and logs. To run the same stateless server on your own infrastructure, follow the [self-hosting guide →](https://mcpuse-codex-v1-v2-docs-split.mintlify.site/v2/typescript/server/deployment/runtime-patterns).
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
## Examples
|
||||
|
||||
[**→ Full Python Agent Documentation**](./libraries/python/README.md#quick-start)
|
||||
Remix a complete MCP App, inspect the source, or deploy it as a starting point:
|
||||
|
||||
### <img src="./static/typescript.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> TypeScript
|
||||
| Preview | App | What it demonstrates |
|
||||
| --- | --- | --- |
|
||||
| <img src="https://raw.githubusercontent.com/mcp-use/mcp-chart-builder/main/repo-assets/demo.gif" alt="Chart Builder demo" width="280"> | [Chart Builder](https://github.com/mcp-use/mcp-chart-builder) | Structured data rendered as interactive charts · [Open demo](https://yellow-shadow-21833.run.mcp-use.com/mcp) |
|
||||
| <img src="https://raw.githubusercontent.com/mcp-use/mcp-diagram-builder/main/repo-assets/demo.gif" alt="Diagram Builder demo" width="280"> | [Diagram Builder](https://github.com/mcp-use/mcp-diagram-builder) | Create and edit diagrams through MCP tools · [Open demo](https://lucky-darkness-402ph.run.mcp-use.com/mcp) |
|
||||
| <img src="https://raw.githubusercontent.com/mcp-use/mcp-maps-explorer/main/repo-assets/demo.gif" alt="Maps Explorer demo" width="280"> | [Maps Explorer](https://github.com/mcp-use/mcp-maps-explorer) | Search, detail tools, and an interactive map view · [Open demo](https://super-night-ttde2.run.mcp-use.com/mcp) |
|
||||
|
||||
```bash
|
||||
npm install @mcp-use/client @mcp-use/agent @langchain/openai
|
||||
```
|
||||
[Browse all TypeScript examples →](./libraries/typescript/packages/server/examples)
|
||||
|
||||
```typescript
|
||||
import { ChatOpenAI } from "@langchain/openai";
|
||||
import { MCPAgent } from "@mcp-use/agent";
|
||||
import { MCPClient } from "@mcp-use/client";
|
||||
## Ecosystem
|
||||
|
||||
async function main() {
|
||||
const config = {
|
||||
mcpServers: {
|
||||
filesystem: {
|
||||
command: "npx",
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
|
||||
},
|
||||
},
|
||||
};
|
||||
| Package | Use it for |
|
||||
| --- | --- |
|
||||
| [`mcp-use`](https://www.npmjs.com/package/mcp-use) | TypeScript v2 server framework, React views, and CLI |
|
||||
| [`@mcp-use/client`](https://www.npmjs.com/package/@mcp-use/client) | Connect to MCP servers from Node.js, browsers, React, and sandboxes |
|
||||
| [`@mcp-use/agent`](https://www.npmjs.com/package/@mcp-use/agent) | Build model-powered agents on top of MCP clients |
|
||||
| [`@mcp-use/inspector`](https://www.npmjs.com/package/@mcp-use/inspector) | Inspect and debug MCP servers and apps |
|
||||
| [`create-mcp-use-app`](https://www.npmjs.com/package/create-mcp-use-app) | Scaffold servers and interactive apps |
|
||||
| [`mcp-use` for Python](https://pypi.org/project/mcp-use/) | Build Python MCP servers, clients, and agents |
|
||||
|
||||
const client = MCPClient.fromDict(config);
|
||||
const llm = new ChatOpenAI({ modelName: "gpt-4o" });
|
||||
const agent = new MCPAgent({ llm, client });
|
||||
- [TypeScript documentation](https://mcp-use.com/docs/typescript)
|
||||
- [Python documentation](https://mcp-use.com/docs/python)
|
||||
- [Inspector documentation](https://mcp-use.com/docs/inspector/index)
|
||||
- [Agent documentation](https://mcp-use.com/docs/typescript/agent/index)
|
||||
- [Client documentation](https://mcp-use.com/docs/typescript/client/index)
|
||||
|
||||
const result = await agent.run("List all files in the directory");
|
||||
console.log(result);
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
[**→ Full TypeScript Agent Documentation**](./libraries/typescript/README.md#-quick-start)
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Use MCP Client</summary>
|
||||
|
||||
### <img src="./static/python.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> Python
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from mcp_use import MCPClient
|
||||
|
||||
async def main():
|
||||
config = {
|
||||
"mcpServers": {
|
||||
"calculator": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-everything"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
client = MCPClient.from_dict(config)
|
||||
await client.create_all_sessions()
|
||||
|
||||
session = client.get_session("calculator")
|
||||
result = await session.call_tool(name="add", arguments={"a": 5, "b": 3})
|
||||
|
||||
print(f"Result: {result.content[0].text}")
|
||||
await client.close_all_sessions()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
[**→ Python Client Documentation**](./libraries/python/README.md#direct-tool-calls-without-llm)
|
||||
|
||||
### <img src="./static/typescript.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> TypeScript
|
||||
|
||||
```typescript
|
||||
import { MCPClient } from "@mcp-use/client";
|
||||
|
||||
async function main() {
|
||||
const config = {
|
||||
mcpServers: {
|
||||
calculator: {
|
||||
command: "npx",
|
||||
args: ["-y", "@modelcontextprotocol/server-everything"],
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
const client = new MCPClient(config);
|
||||
await client.createAllSessions();
|
||||
|
||||
const session = client.getSession("calculator");
|
||||
const result = await session.callTool("add", { a: 5, b: 3 });
|
||||
|
||||
console.log(`Result: ${result.content[0].text}`);
|
||||
await client.closeAllSessions();
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
[**→ TypeScript Client Documentation**](./libraries/typescript/README.md#basic-usage)
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Conformance to Model Context Protocol
|
||||
## Protocol conformance
|
||||
|
||||
<div align="center">
|
||||
<a href="https://github.com/mcp-use/mcp-use/actions/workflows/conformance.yml" alt="Python MCP Conformance">
|
||||
<img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tonxxd/6edf670f0446dc9f7a1f32d6bfda2b70/raw/python-conformance.json" /></a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/actions/workflows/conformance.yml" alt="Python MCP Client Conformance">
|
||||
<img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tonxxd/6edf670f0446dc9f7a1f32d6bfda2b70/raw/python-client-conformance.json" /></a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/actions/workflows/conformance.yml" alt="TypeScript MCP Conformance">
|
||||
<img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tonxxd/6edf670f0446dc9f7a1f32d6bfda2b70/raw/typescript-conformance.json" /></a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/actions/workflows/conformance.yml" alt="TypeScript MCP Client Conformance">
|
||||
<img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tonxxd/6edf670f0446dc9f7a1f32d6bfda2b70/raw/typescript-node-client-conformance.json" /></a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/actions/workflows/conformance.yml">
|
||||
<img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tonxxd/6edf670f0446dc9f7a1f32d6bfda2b70/raw/python-conformance.json" alt="Python MCP conformance">
|
||||
</a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/actions/workflows/conformance.yml">
|
||||
<img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tonxxd/6edf670f0446dc9f7a1f32d6bfda2b70/raw/python-client-conformance.json" alt="Python MCP client conformance">
|
||||
</a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/actions/workflows/conformance.yml">
|
||||
<img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tonxxd/6edf670f0446dc9f7a1f32d6bfda2b70/raw/typescript-conformance.json" alt="TypeScript MCP conformance">
|
||||
</a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/actions/workflows/conformance.yml">
|
||||
<img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tonxxd/6edf670f0446dc9f7a1f32d6bfda2b70/raw/typescript-node-client-conformance.json" alt="TypeScript MCP client conformance">
|
||||
</a>
|
||||
</div>
|
||||
|
||||
---
|
||||
## Security and community
|
||||
|
||||
## Security
|
||||
|
||||
See [SECURITY.md](https://github.com/mcp-use/mcp-use/blob/main/SECURITY.md)
|
||||
|
||||
## Community & Support
|
||||
|
||||
- **Discord**: [Join our community](https://discord.gg/XkNkSkMz3V)
|
||||
- **GitHub Issues**: [Report bugs or request features](https://github.com/mcp-use/mcp-use/issues)
|
||||
- **Documentation**: [mcp-use.com/docs](https://mcp-use.com/docs)
|
||||
- **Website**: [manufact.com](https://manufact.com)
|
||||
- **X.com**: Follow [Manufact](https://x.com/manufact)
|
||||
- **Contributing**: See [CONTRIBUTING.md](https://github.com/mcp-use/mcp-use/blob/main/CONTRIBUTING.md)
|
||||
- **License**: MIT © [MCP-Use Contributors](https://github.com/mcp-use/mcp-use/graphs/contributors)
|
||||
|
||||
---
|
||||
|
||||
## Star History
|
||||
|
||||
[](https://www.star-history.com/#mcp-use/mcp-use&Date)
|
||||
|
||||
---
|
||||
- [Security policy](./SECURITY.md)
|
||||
- [Contribution guide](./CONTRIBUTING.md)
|
||||
- [GitHub issues](https://github.com/mcp-use/mcp-use/issues)
|
||||
- [Discord community](https://discord.gg/XkNkSkMz3V)
|
||||
- [Manufact](https://manufact.com)
|
||||
- [MIT license](./LICENSE)
|
||||
|
||||
## Contributors
|
||||
|
||||
Thanks to all our amazing contributors!
|
||||
|
||||
### Core Contributors
|
||||
|
||||
1. **Pietro** ([@pietrozullo](https://github.com/pietrozullo))
|
||||
2. **Luigi** ([@pederzh](https://github.com/pederzh))
|
||||
3. **Enrico** ([@tonxxd](https://github.com/tonxxd))
|
||||
|
||||
<br>
|
||||
Built by [Pietro](https://github.com/pietrozullo), [Luigi](https://github.com/pederzh), [Enrico](https://github.com/tonxxd), and the mcp-use community.
|
||||
|
||||
<a href="https://github.com/mcp-use/mcp-use/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=mcp-use/mcp-use" />
|
||||
<img src="https://contrib.rocks/image?repo=mcp-use/mcp-use" alt="mcp-use contributors">
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<strong>Built with ❤️ by Manufact team and the mcp-use community</strong>
|
||||
<br/>
|
||||
<sub>San Francisco | Zürich</sub>
|
||||
</div>
|
||||
|
||||
+261
@@ -0,0 +1,261 @@
|
||||
# mcp-use SDK v2 benchmarks
|
||||
|
||||
This report compares the published `mcp-use@2.0.0-beta.61` package with
|
||||
mcp-use v1, the official TypeScript SDK, and representative TypeScript MCP
|
||||
frameworks. It was recorded on July 27, 2026 using Node.js 24.15.0.
|
||||
|
||||
## Results at a glance
|
||||
|
||||
Compared with mcp-use v1, v2 measured:
|
||||
|
||||
- **27% higher median throughput:** 8,615.0 → 10,982.2 operations per second
|
||||
- **55% lower cold-launch time:** 151.603 → 68.145 ms
|
||||
- **82% smaller clean install:** 404.6 → 74.4 MiB
|
||||
- **84% fewer installed packages:** 365 → 57
|
||||
- **70% smaller npm tarball:** 1,155 → 346 KiB
|
||||
- **36% smaller equivalent MCP App build:** 1.289 → 0.828 MB
|
||||
|
||||
## Throughput
|
||||
|
||||
**Higher is better.** Black is mcp-use v2; gray represents the other
|
||||
TypeScript fixtures.
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
themeVariables:
|
||||
xyChart:
|
||||
backgroundColor: "#ffffff"
|
||||
titleColor: "#0c0c0c"
|
||||
xAxisLabelColor: "#0c0c0c"
|
||||
xAxisTitleColor: "#0c0c0c"
|
||||
xAxisTickColor: "#0c0c0c"
|
||||
xAxisLineColor: "#0c0c0c"
|
||||
yAxisLabelColor: "#0c0c0c"
|
||||
yAxisTitleColor: "#0c0c0c"
|
||||
yAxisTickColor: "#0c0c0c"
|
||||
yAxisLineColor: "#0c0c0c"
|
||||
plotColorPalette: "#0c0c0c, #d4d4d8"
|
||||
---
|
||||
xychart
|
||||
title "Median operations per second"
|
||||
x-axis ["tmcp", "mcp-use v2", "mcp-use v1", "Skybridge", "Official v2", "Official v1", "xmcp", "mcp-handler"]
|
||||
y-axis "operations per second" 0 --> 20000
|
||||
bar [0, 10982, 0, 0, 0, 0, 0, 0]
|
||||
bar [18425, 0, 8615, 8116, 8050, 6914, 6585, 6324]
|
||||
```
|
||||
|
||||
mcp-use v2 delivered **10,982.2 median operations per second**, 27.5% above
|
||||
mcp-use v1 and 36.4% above the equivalent official TypeScript SDK v2 fixture.
|
||||
|
||||
Custom stateless request handling and optimized response paths on top of the
|
||||
official SDK made mcp-use v2 the fastest TypeScript framework with native MCP
|
||||
Apps support in this test.
|
||||
|
||||
| Framework | Version | Protocol | Median ops/s | p95 | p99 | Stability |
|
||||
| --- | --- | --- | ---: | ---: | ---: | ---: |
|
||||
| tmcp | 1.19.4 | 2025-06-18 | 18,424.5 | 2 ms | 3 ms | 100 |
|
||||
| **mcp-use v2** | **2.0.0-beta.61** | **2026-07-28** | **10,982.2** | **4 ms** | **6 ms** | **100** |
|
||||
| mcp-use v1 | 1.34.5 | 2025-11-25 | 8,615.0 | 4 ms | 6 ms | 100 |
|
||||
| Skybridge | 1.2.6 | 2025-11-25 | 8,116.4 | 4 ms | 6 ms | 100 |
|
||||
| Official SDK v2 | 2.0.0-beta.5 | 2026-07-28 | 8,049.8 | 5 ms | 7 ms | 100 |
|
||||
| Official SDK v1 | 1.29.0 | 2025-11-25 | 6,914.1 | 5 ms | 7 ms | 100 |
|
||||
| xmcp | 0.6.13 | 2025-11-25 | 6,585.1 | 6 ms | 8 ms | 100 |
|
||||
| mcp-handler | 1.1.0 | 2025-11-25 | 6,324.4 | 6 ms | 9 ms | 100 |
|
||||
|
||||
## Cold launch
|
||||
|
||||
**Lower is better.** Each result is the median of 100 recorded process starts
|
||||
after 10 warmups, with launch order rotated across all targets.
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
themeVariables:
|
||||
xyChart:
|
||||
backgroundColor: "#ffffff"
|
||||
titleColor: "#0c0c0c"
|
||||
xAxisLabelColor: "#0c0c0c"
|
||||
xAxisTitleColor: "#0c0c0c"
|
||||
xAxisTickColor: "#0c0c0c"
|
||||
xAxisLineColor: "#0c0c0c"
|
||||
yAxisLabelColor: "#0c0c0c"
|
||||
yAxisTitleColor: "#0c0c0c"
|
||||
yAxisTickColor: "#0c0c0c"
|
||||
yAxisLineColor: "#0c0c0c"
|
||||
plotColorPalette: "#0c0c0c, #d4d4d8"
|
||||
---
|
||||
xychart
|
||||
title "Median cold launch in milliseconds"
|
||||
x-axis ["Official v2", "mcp-use v2", "xmcp", "tmcp", "Official v1", "mcp-use v1", "mcp-handler", "Skybridge"]
|
||||
y-axis "milliseconds" 0 --> 180
|
||||
bar [0, 68.145, 0, 0, 0, 0, 0, 0]
|
||||
bar [67.839, 0, 68.814, 77.740, 108.039, 151.603, 158.498, 168.260]
|
||||
```
|
||||
|
||||
| Framework | Median | Interquartile range |
|
||||
| --- | ---: | ---: |
|
||||
| Official SDK v2 | 67.839 ms | 66.881–69.522 ms |
|
||||
| **mcp-use v2** | **68.145 ms** | **67.049–69.306 ms** |
|
||||
| xmcp | 68.814 ms | 67.894–70.376 ms |
|
||||
| tmcp | 77.740 ms | 76.678–79.388 ms |
|
||||
| Official SDK v1 | 108.039 ms | 106.498–110.417 ms |
|
||||
| mcp-use v1 | 151.603 ms | 149.258–154.942 ms |
|
||||
| mcp-handler | 158.498 ms | 155.539–162.677 ms |
|
||||
| Skybridge | 168.260 ms | 166.513–171.449 ms |
|
||||
|
||||
The mcp-use v2 and official SDK v2 distributions overlap. Their 0.306 ms
|
||||
median difference is measurement noise, not a meaningful product advantage.
|
||||
|
||||
## Install footprint
|
||||
|
||||
**Lower is better.** This comparison is intentionally limited to the
|
||||
full-stack frameworks tested with a native MCP Apps build workflow. Low-level
|
||||
libraries with a narrower scope are not equivalent install targets.
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
themeVariables:
|
||||
xyChart:
|
||||
backgroundColor: "#ffffff"
|
||||
titleColor: "#0c0c0c"
|
||||
xAxisLabelColor: "#0c0c0c"
|
||||
xAxisTitleColor: "#0c0c0c"
|
||||
xAxisTickColor: "#0c0c0c"
|
||||
xAxisLineColor: "#0c0c0c"
|
||||
yAxisLabelColor: "#0c0c0c"
|
||||
yAxisTitleColor: "#0c0c0c"
|
||||
yAxisTickColor: "#0c0c0c"
|
||||
yAxisLineColor: "#0c0c0c"
|
||||
plotColorPalette: "#0c0c0c, #d4d4d8"
|
||||
---
|
||||
xychart
|
||||
title "Clean production install in MiB"
|
||||
x-axis ["mcp-use v2", "xmcp", "Skybridge", "mcp-use v1"]
|
||||
y-axis "MiB on disk" 0 --> 450
|
||||
bar [74.4, 0, 0, 0]
|
||||
bar [0, 121.9, 137.5, 404.6]
|
||||
```
|
||||
|
||||
| Framework | Direct install set | Disk | Installed packages |
|
||||
| --- | --- | ---: | ---: |
|
||||
| **mcp-use v2** | `mcp-use + zod` | **74.4 MiB** | **57** |
|
||||
| xmcp | `xmcp + zod` | 121.9 MiB | 171 |
|
||||
| Skybridge | `skybridge + zod` | 137.5 MiB | 300 |
|
||||
| mcp-use v1 baseline | `mcp-use + zod` | 404.6 MiB | 365 |
|
||||
|
||||
mcp-use v2 had the smallest clean install among the tested full-stack native
|
||||
MCP Apps frameworks. The mcp-use v1 row is a migration baseline, not a native
|
||||
Apps peer.
|
||||
|
||||
## Package and MCP App build size
|
||||
|
||||
The published `mcp-use` v2 npm tarball measured **346 KiB compressed**, 70.0%
|
||||
smaller than v1's 1,155 KiB tarball.
|
||||
|
||||
For the application build, both versions used the same React launch card, CSS,
|
||||
and one echo tool.
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
themeVariables:
|
||||
xyChart:
|
||||
backgroundColor: "#ffffff"
|
||||
titleColor: "#0c0c0c"
|
||||
xAxisLabelColor: "#0c0c0c"
|
||||
xAxisTitleColor: "#0c0c0c"
|
||||
xAxisTickColor: "#0c0c0c"
|
||||
xAxisLineColor: "#0c0c0c"
|
||||
yAxisLabelColor: "#0c0c0c"
|
||||
yAxisTitleColor: "#0c0c0c"
|
||||
yAxisTickColor: "#0c0c0c"
|
||||
yAxisLineColor: "#0c0c0c"
|
||||
plotColorPalette: "#0c0c0c, #d4d4d8"
|
||||
---
|
||||
xychart
|
||||
title "Equivalent MCP App production build"
|
||||
x-axis ["mcp-use v2", "mcp-use v1"]
|
||||
y-axis "megabytes" 0 --> 1.4
|
||||
bar [0.828, 0]
|
||||
bar [0, 1.289]
|
||||
```
|
||||
|
||||
| Version | Raw build | gzip archive | Files |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| **mcp-use v2** | **0.828 MB** | **214 KiB** | **4** |
|
||||
| mcp-use v1 | 1.289 MB | 351 KiB | 12 |
|
||||
|
||||
v2 was 35.8% smaller raw and 39.1% smaller after gzip. We do not present a
|
||||
cross-framework build-size leaderboard because the other projects emit
|
||||
different server and UI artifact boundaries.
|
||||
|
||||
## How this relates to the official SDK
|
||||
|
||||
mcp-use builds on the official `@modelcontextprotocol/core`, `server`, and
|
||||
`client` packages for protocol compatibility. It adds a typed server API,
|
||||
custom stateless request and response paths, generated tool-to-View contracts,
|
||||
scaffolding, Inspector integration, verification, and deployment workflows.
|
||||
|
||||
The official server package is the low-level protocol baseline in this report.
|
||||
MCP Apps are available through the separate `@modelcontextprotocol/ext-apps`
|
||||
extension and application-specific resource, metadata, build, and type wiring.
|
||||
mcp-use makes Views a native framework feature and carries their contracts from
|
||||
the tool definition through React and the Inspector.
|
||||
|
||||
mcp-use adds framework-level performance improvements on top of the official
|
||||
SDK, including custom stateless request handling and optimized response paths.
|
||||
Those improvements delivered **36.4% higher median throughput** than the
|
||||
equivalent official SDK v2 fixture in this benchmark.
|
||||
|
||||
## Methodology
|
||||
|
||||
### Load workload
|
||||
|
||||
- Published packages were tested instead of local source builds.
|
||||
- The load generator was MCP Drill at source commit
|
||||
`284244af63efb109959ccf3cecea0000bad3bfe3`.
|
||||
- Every server exposed the same `benchmark_echo` tool.
|
||||
- The operation mix was one `tools/list` call for every nine `tools/call`
|
||||
operations.
|
||||
- Each run used a 3-second preflight, 5 virtual users for 5 seconds, then a
|
||||
15-second ramp to 50 virtual users.
|
||||
- Three rounds rotated target order. Every target received a fresh framework
|
||||
process and fresh MCP Drill control and worker containers.
|
||||
- Reported throughput and latency values are medians across the three accepted
|
||||
rounds.
|
||||
- All eight TypeScript targets received MCP Drill's stability score of 100.
|
||||
|
||||
### Launch workload
|
||||
|
||||
- Every target received 10 warmup launches and 100 recorded launches.
|
||||
- Target order rotated on every round.
|
||||
- Timing started before process creation and stopped when the TCP listener
|
||||
accepted a connection.
|
||||
- Each process was terminated before the next sample.
|
||||
|
||||
### Install and build measurements
|
||||
|
||||
- Clean install size is the on-disk dependency tree after installing the direct
|
||||
package set shown in the table.
|
||||
- Tarball size is the compressed size reported from the published npm package.
|
||||
- The v1 and v2 App builds use equivalent source content and production build
|
||||
settings.
|
||||
|
||||
## Limits and claim boundaries
|
||||
|
||||
- Absolute localhost results move with machine load, scheduler behavior, and
|
||||
thermal conditions.
|
||||
- The TypeScript throughput field spans protocol generations and framework
|
||||
scopes.
|
||||
- Install comparisons are meaningful only when the tested package scope is
|
||||
equivalent.
|
||||
- Production builds are compared only between mcp-use v1 and v2 because the
|
||||
other frameworks emit different artifact boundaries.
|
||||
- Two incomplete controller-capacity attempts were rejected and excluded from
|
||||
every result above.
|
||||
- There is no composite “overall score.”
|
||||
|
||||
Use the scoped result: **fastest TypeScript framework with native MCP Apps
|
||||
support in this eight-fixture test**.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 89 KiB |
Reference in New Issue
Block a user