用 Gradio， 几行 Python 代码构建 MCP 服务器！

大家好，我是i学习的老章

大模型世界变化太快，RAG、Agent之后，MCP开始火热了，我之前也有过介绍：

微软这次真把Markdown玩明白了，接入_MCP_

GitHub 仓库的免费百科全书，加上_MCP_ 如虎添翼

前些天，吴恩达老师新推出一门免费 MCP 学习短课程： 刚刚，吴恩达新推出一门免费短课，通过实践项目强化学习，学习如何使用 MCP 标准化 LLM 与外部工具、数据、提示词的连接方式。

本文向大家介绍一个更强悍玩法——利用 Gradio 轻松构建 MCP (Model-as-a-Plugin) 服务器，并探索 Hugging Face Hub 上的 Agents，从而为您的语言模型（LLM）赋予更强大的工具使用能力。

理解 MCP (Model-as-a-Plugin)

MCP (Model-as-a-Plugin) 是一种标准化协议，它允许语言模型（LLM）发现并使用外部工具。想象一下，LLM 就像一个聪明的大脑，而 MCP 工具则是它能调用的各种“手”和“脚”，使其能够执行超出其内置能力的特定任务，例如：

• 图像生成与编辑
• 音频合成
• 复杂的数学计算
• 与外部 API 交互

通过 MCP 服务器，开发者可以将任何功能封装成一个 LLM 可以理解和使用的工具，从而极大地增强 LLM 的实用性和应用范围。

使用 Gradio 构建 MCP 服务器

Gradio 是一个出色的 Python 库，以其能够快速创建用户友好的机器学习应用界面而闻名。更棒的是，Gradio 现在使得构建 MCP 服务器也变得异常简单。

五行 Python 代码构建 MCP 服务器

是的，你没有看错！只需几行代码，就能将一个普通的 Python 函数转换成一个功能完备的 MCP 工具。让我们看一个简单的例子——一个计算特定字母在单词中出现次数的工具：

import gradio as gr

def letter_counter(word: str, letter: str) -> int:
    """
    计算一个单词或短语中特定字母出现的次数。
    
    Args:
        word: 要分析的单词或短语。
        letter: 要计数的字母。
        
    Returns:
        该字母在单词中出现的次数。
    """
    return word.lower().count(letter.lower())

demo = gr.Interface(
    fn=letter_counter,
    inputs=["text", "text"],
    outputs="number",
    title="字母计数器",
    description="计算一个字母在单词中出现的次数"
)

# 关键在于此：启动 Gradio 应用并将其作为 MCP 服务器
demo.launch(mcp_server=True)

当您运行此应用时，Gradio 不仅会启动常规的 Web 界面，还会启动一个 MCP 服务器。您会在控制台中看到 MCP 服务器的 URL，通常格式如下：http://your-server:port/gradio_api/mcp/sse

Gradio 会自动将 letter_counter 函数转换为一个 MCP 工具。函数的文档字符串（docstring）——尤其要注意 Args: 部分描述参数的特定格式——以及 Python 的类型提示，都会被用来自动生成工具的模式（schema），供 LLM 理解和使用。

Gradio 与 MCP 集成的主要特性

Gradio 与 MCP 的集成为开发者提供了许多便利：

1. 自动工具转换: Gradio 应用中的每个 API 端点都会自动转换为一个 MCP 工具，包含相应的名称、描述和输入/输出模式 (schema)。您可以访问 http://your-server:port/gradio_api/mcp/schema 或点击 Gradio 应用页脚的 "View API" 链接，然后选择 "MCP" 来查看这些工具和模式。

2. 环境变量支持: 除了在 launch() 方法中设置 mcp_server=True，您还可以通过设置环境变量来启用 MCP 服务器功能：

   
   
   
       
   export GRADIO_MCP_SERVER=True
   

3. 强大的文件处理: MCP 服务器会自动处理文件数据的转换，包括：

• 将 Base64 编码的字符串转换为文件数据。
• 处理图像文件并以正确的格式返回。
• 管理临时文件存储。
• 重要提示: 强烈建议将输入的图像和文件作为完整的 URL (http://... 或 https://...) 传递，因为 MCP 客户端并非总能正确处理本地文件。

连接到 MCP 客户端

拥有了 Gradio MCP 服务器后，您需要将其添加到您的 MCP 客户端（如 Cursor, Cline, Tiny Agents 等）的配置中。通常，这只需要将以下 JSON 配置粘贴到客户端的设置中：

{
  "mcpServers": {
    "gradio_letter_counter": {  // 您可以为您的服务器起一个描述性的名字
      "url": "http://127.0.0.1:7860/gradio_api/mcp/sse" // 替换为您的实际服务器地址和端口
    }
  }
}

对于某些尚不支持基于 SSE (Server-Sent Events) 的 MCP 服务器的客户端（如 Claude Desktop 的早期版本），您可以使用像 mcp-remote 这样的工具。

Gradio 作为 MCP 客户端

值得注意的是，Gradio 不仅仅能用作 MCP 服务器 来提供工具，它本身也可以用来构建 MCP 客户端。例如，一个 gr.Chatbot 聊天界面可以被赋予能力，通过 MCP 协议调用外部 MCP 服务器上定义的工具。

在这种典型的场景中，Gradio UI（如聊天机器人）会接收用户输入，并将其传递给一个大型语言模型（LLM）。LLM 在处理用户请求后，可能会决定需要使用一个或多个外部工具。此时，Gradio 应用中的 MCP 客户端逻辑会负责与相应的 MCP 服务器通信，执行工具调用，并将结果返回给 LLM，最终呈现给用户。

这种方式使得 Gradio 应用既能提供友好的用户交互，又能集成强大的外部工具能力。想了解如何用 Gradio 构建 MCP 客户端的详细步骤和示例（例如，一个使用 Claude API 并能通过 MCP 调用图像生成工具的聊天机器人），请参阅 Gradio 官方指南：构建 MCP 客户端^[2]。

高级：使用 gradio_client 构建自定义 MCP 服务器

对于需要更精细控制的场景，例如：

• 从一个大型 Gradio 应用中选择特定的 API 端点作为工具。
• 自定义工具如何呈现给 LLM（例如，修改 schema 或描述）。
• 在工具被调用时才按需启动 Gradio 应用 MCP 服务器（如果本地运行多个 Gradio 应用以节省资源）。
• 使用除 SSE 之外的其他 MCP 协议（如 stdio）。

开发者可以利用 gradio_client Python 库与 Gradio 应用进行交互，并结合 mcp Python SDK (例如 mcp.server.fastmcp) 来构建自定义的 MCP 服务器。这种方法允许您创建更复杂、更灵活的工具服务器架构，例如，一个统一的 MCP 服务器代理多个不同的 Gradio 应用（甚至是托管在 Hugging Face Spaces 上的应用）。

关于如何实现自定义 MCP 服务器的详细指南和代码示例，请参阅 Gradio 官方文档：构建 MCP 服务器^[3]中的相关部分。

Hugging Face Hub 上的 Agents

Hugging Face Hub 不仅仅是模型和数据集的中心，它也为 Agentic 工作流程提供了强大的库和工具。

smolagents

smolagents 是一个轻量级的 Python 库，旨在用几行代码覆盖从代码编写 Agents 到计算机使用的所有 Agentic 用例。它的特点包括：

• 模型无关: 支持通过 Hugging Face Transformers 提供的本地模型、通过 Inference Endpoints 托管的模型，以及其他专有模型提供商。
• 独特的 CodeAgent: 一种能够用 Python 代码编写其动作的 Agent。
• 标准的 ToolCallingAgent: 以大多数 Agentic 框架所采用的 JSON 对象形式编写动作。
• CLI 工具: 通过 smolagent 命令可以轻松启动一个 Agent。

  smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7." \
  --model-type "InferenceClientModel" \
  --model-id "Qwen/Qwen2.5-Coder-32B-Instruct" \
  --imports "pandas numpy" \
  --tools "web_search"
  

• 与 MCP 服务器集成: smolagents 可以无缝使用 MCP 服务器作为其工具集的一部分。

  from smolagents import MCPClient, CodeAgent
  from mcp import StdioServerParameters # 或者 UrlServerParameters
  import os
  
  # 示例：使用一个通过 URL 访问的 Gradio MCP 服务器
  # server_parameters = UrlServerParameters(url="http://127.0.0.1:7860/gradio_api/mcp/sse")
  
  # 示例：使用一个通过命令行启动的 MCP 服务器 (如 pubmedmcp)
  server_parameters = StdioServerParameters(
      command="uvx",
      args=["--quiet", "pubmedmcp@0.1.3"],
      env={"UV_PYTHON": "3.12", **os.environ},
  )
  
  # 假设您有一个已经实例化的 LLM 模型 `model`
  # model = ... 
  
  with MCPClient(server_parameters) as tools:
      agent = CodeAgent(tools=tools, model=model, add_base_tools=True) # model 需要您自行提供
      agent.run("Please find the latest research on COVID-19 treatment.")
  

• 分享到 Hub: 您可以将构建的 Agents 作为 Spaces 推送到 Hugging Face Hub 与社区分享。

huggingface.js mcp-client

对于 JavaScript 开发者，Hugging Face 提供了 @huggingface/mcp-client。这个 MCP 客户端可以与通过 Hugging Face Inference Endpoints 提供的模型或本地运行的 LLM 一起使用。

• 快速启动: 通过 npx @huggingface/mcp-client (或 pnpm agent 在其项目中) 即可开始。
• 灵活配置: 通过环境变量（如 PROVIDER, MODEL_ID, ENDPOINT_URL）轻松切换不同的模型和提供商。
• 使用 Hugging Face Inference Endpoints:

  export HF_TOKEN="hf_..."
  export MODEL_ID="Qwen/Qwen2.5-72B-Instruct"
  export PROVIDER="huggingface" # 或其他如 'nebius'
  npx @huggingface/mcp-client
  

• 使用本地 LLM (例如通过 lmstudio):

  ENDPOINT_URL=http://localhost:1234/v1 \
  MODEL_ID=lmstudio-community/Qwen3-14B-GGUF \
  npx @huggingface/mcp-client
  

结合 Gradio MCP 和 Hub Agents 的强大能力

Gradio MCP 服务器与 Hugging Face Hub 上的 Agents 工具（如 smolagents 和 huggingface.js mcp-client）的结合，为开发者构建高级 AI 应用开辟了广阔的可能性。

想象一下：

• 您可以快速将现有的 Python 工具或新的机器学习模型通过 Gradio 封装为 MCP 工具。
• 然后，使用 smolagents 或 huggingface.js 构建的 Agents 可以轻松地发现并使用这些工具来完成复杂任务。
• 成千上万的 Gradio 应用托管在 Hugging Face Spaces 上，它们中的许多都可以通过简单的 mcp_server=True 配置，立即转变为可供 Agents 使用的强大工具库。

这种组合使得扩展 LLM 的能力变得前所未有的简单和高效。

检修 Gradio MCP 集成

MCP 生态系统仍在不断发展和完善中。如果您在构建或连接 Gradio MCP 服务器/客户端时遇到问题，以下是一些排查建议：

1. 使用 MCP Inspector 工具: MCP Inspector 工具^[4] 是一个通用的 MCP 调试工具，可以帮助您检查 MCP 服务器的响应和工具定义是否符合预期。

2. 检查 Docstrings 和类型提示:

• 确保您暴露为工具的 Python 函数拥有清晰、格式正确的文档字符串（docstring）。特别是 Args: 部分，它用于描述每个参数，Gradio 会利用它来生成工具的 schema。
• 同时，Python 的类型提示（type hints）也非常重要。
• 您可以通过访问 MCP 服务器的 schema URL (http://your-server:port/gradio_api/mcp/schema) 来预览 Gradio 为您的工具生成的 schema 定义。

• 虽然 Gradio 和 MCP 支持多种数据类型，但某些 MCP 客户端可能对参数类型的处理不够健壮，尤其是对于数字或复杂类型。
• 如果遇到问题，尝试将函数参数的类型提示改为 str，并在函数内部进行显式的类型转换。这通常能提高与各种 MCP 客户端的兼容性。

• Gradio MCP 服务器默认使用 Server-Sent Events (SSE) 协议。请确认您的 MCP 客户端支持 SSE。
• 对于不支持 SSE 的客户端（例如某些旧版本的 Claude Desktop），可以考虑使用 mcp-remote^[5] 工具作为桥接。这需要您安装 Node.js，并在 MCP 客户端配置中通过命令行方式调用 mcp-remote 指向您的 Gradio SSE 端点。

• 有时，简单的重启就能解决问题。尝试重启您的 MCP 客户端，以及您的 Gradio MCP 服务器。
• 特别是在修改了 MCP 配置或服务器代码后，确保更改已生效。

进一步阅读

• Gradio 官方文档^[6]
• Hugging Face Hub Agents 文档^[7]
• smolagents 文档^[8]
• huggingface.js mcp-client 文档^[9]