mcp-use/mcp-use · 上手攻略

• 仓库：mcp-use/mcp-use
• 链接：https://github.com/mcp-use/mcp-use
• 分类：skill
• 作者：Jay
• 更新：2026-07-14

这是什么

mcp-use 是一个全栈 MCP（Model Context Protocol）开发框架，帮助开发者快速构建 MCP Servers（工具服务器）和 MCP Apps（可交互的 AI 应用组件），同时提供 MCP Client / MCP Agent 客户端实现，内置 Web 版 Inspector 调试工具，并支持一键部署到 Manufact MCP Cloud。

换句话说，如果你想给 Claude、ChatGPT 这类 AI 助手编写自定义工具（tools），或者想让 AI 在对话里渲染一个可交互的 React 小组件，mcp-use 就是目前上手体验最好的框架之一。

项目由 Manufact 团队维护，提供 TypeScript（npm）和 Python（pip）双语言 SDK，MIT 协议开源。

解决什么问题

MCP 协议本身只定义了通信规范，从零实现一个符合规范的服务器需要处理传输层（stdio / streamable-http）、schema 验证、日志、部署等一系列工作。mcp-use 把这些全部封装好，让开发者只专注写业务逻辑。

典型痛点： - 想快速验证一个 MCP 工具，但没有好用的脚手架 - 需要在 AI 对话中展示交互式 UI 组件（如图表、地图、幻灯片），而不是返回纯文字 - 需要连接多个 MCP Server 构建 Agent，同时调试多个工具 - 需要一个可分享的 MCP App，让不同 AI 客户端（Claude / ChatGPT）都能用

快速安装

TypeScript / Node.js

# 脚手架（推荐）
npx create-mcp-use-app@latest

# 或手动安装
npm install mcp-use
npm install -D typescript @types/node

Python

pip install mcp-use

前置依赖

• Node.js ≥ 18（TypeScript）
• Python ≥ 3.10（Python SDK）
• Docker（可选，用于运行 Inspector 或部署）

核心用法

1. 创建一个 MCP Server（TypeScript）

import { MCPServer, text } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "my-server",
  version: "1.0.0",
});

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);
// 调试界面：http://localhost:3000/inspector

2. 创建一个 MCP App（含交互 Widget）

MCP App 的核心是工具 + 对应 Widget。工具返回 widget() 对象，指定一个 React 组件路径，AI 客户端渲染该组件。

Server 端（工具定义）：

import { MCPServer, widget } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "weather-app",
  version: "1.0.0",
});

server.tool({
  name: "get-weather",
  description: "Get weather for a city",
  schema: z.object({ city: z.string() }),
  widget: "weather-display", // 关联 Widget 路径
}, async ({ city }) => {
  return widget({
    props: { city, temperature: 22, conditions: "Sunny" },
    message: `Weather in ${city}: Sunny, 22°C`,
  });
});

await server.listen(3000);

Widget 组件（resources/weather-display/widget.tsx）：

import { useWidget, type WidgetMetadata } from "mcp-use/react";
import { z } from "zod";

const propSchema = z.object({
  city: z.string(),
  temperature: z.number(),
  conditions: z.string(),
});

export const widgetMetadata: WidgetMetadata = {
  description: "Display weather information",
  props: propSchema,
};

const WeatherDisplay: React.FC = () => {
  const { props, isPending, theme } = useWidget<z.infer<typeof propSchema>>();
  const isDark = theme === "dark";

  if (isPending) return <div>Loading...</div>;

  return (
    <div style={{
      background: isDark ? "#1a1a2e" : "#f0f4ff",
      borderRadius: 16, padding: 24,
    }}>
      <h2>{props.city}</h2>
      <p>{props.temperature}° — {props.conditions}</p>
    </div>
  );
};

export default WeatherDisplay;

Widget 放在 resources/ 目录下自动被发现，无需手动注册。

3. 用 MCP Agent 调用其他 MCP Server

import { MCPAgent, MCPClient } from "mcp-use";
import { ChatOpenAI } from "@langchain/openai";

async function main() {
  const config = {
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      },
    },
  };

  const client = new MCPClient(config);
  const llm = new ChatOpenAI({ modelName: "gpt-4o" });
  const agent = new MCPAgent({ llm, client });

  const result = await agent.run("List all files in the directory");
  console.log(result);
}

main();

Python 版：

import asyncio
from mcp_use import MCPAgent, MCPClient
from langchain_openai import ChatOpenAI

async def main():
    config = {
        "mcpServers": {
            "filesystem": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
            }
        }
    }
    client = MCPClient.from_dict(config)
    llm = ChatOpenAI(model="gpt-4o")
    agent = MCPAgent(llm=llm, client=client)
    result = await agent.run("List all files in the directory")
    print(result)

asyncio.run(main())

4. 内置 Inspector 调试

启动服务后直接访问 http://localhost:3000/inspector，或用命令行检查任意已运行的 MCP Server：

npx @mcp-use/inspector --url http://localhost:3000/mcp

5. 部署到 Manufact MCP Cloud

npx @mcp-use/cli login
npx @mcp-use/cli deploy

或在 manufact.com 连接 GitHub 仓库一键部署。

典型适用场景

坑与注意

1. Widget 只在支持的客户端渲染：不是所有 MCP 客户端都支持 MCP App Widget 协议，当前主要是 Claude（官方 MCP 实现）和部分支持 MCP App 的平台。纯文字工具则所有客户端通用。

2. Python SDK 异步陷阱：Python 版所有调用均为异步，必须使用 asyncio.run() 或在 async 函数中调用，不要混用同步代码。

3. Zod schema 是必须的：TypeScript 版必须传 Zod schema 定义工具参数，无法省略，否则类型安全无法保证。

4. Inspector 端口占用：默认 3000（TS）/ 8000（Python），确保端口未被占用，或手动指定其他端口。

5. resources/ 路径约定：Widget 组件必须放在 resources/{name}/widget.tsx，且 widget 名称必须与工具定义的 widget 字段一致，大小写敏感。

6. MCP App 的 props 必须在 widget 函数调用时传：Widget 的 props 是由工具返回时注入的，不是由 AI 生成的，所以需要工具预先知道要显示什么数据。

与同类对比

官方 MCP SDK 是最基础的协议实现，需要自己处理很多东西；mcp-use 在官方基础上大幅提升 DX，尤其在 Widget 和 Agent 层面有独特价值。

一句话结论

想给 AI 写工具或做可视化交互组件？mcp-use 是目前 TypeScript/Python 双语言体验最好、生态最完整的 MCP 框架，30 分钟就能做出可上线的东西。