只改一行代码让你的Gradio应用秒变MCP Server
alitrack约 10 分钟什么是Gradio
Gradio 是一个开源的 Python 库，主要用于快速创建和分享机器学习模型的交互式界面。以下是关于 Gradio 的简要介绍：
1. 功能特点
• 快速搭建界面：通过简单的代码，可以为机器学习模型快速生成交互式界面。例如，只需几行代码，就可以将一个图像分类模型封装成一个带有图像上传和结果显示的 Web 应用。 • 支持多种输入输出类型：支持多种输入（如文本、图像、音频、视频等）和输出（如文本、图像、音频、视频、表格等）类型，能够满足不同类型模型的需求。 • 易于分享：生成的界面可以通过链接分享给他人，方便团队协作和展示模型效果。此外，还可以将界面部署到云平台，如 Hugging Face Spaces 等，实现更广泛的访问。 • 自定义程度高：虽然默认的界面风格简洁美观，但用户也可以通过自定义 CSS 等方式对界面进行个性化调整，以满足特定的视觉需求。
2. 使用场景
• 模型展示：在学术研究、项目汇报等场景中，可以方便地展示模型的功能和效果，让非技术背景的人员也能直观地了解模型的作用。 • 快速原型开发：在开发过程中，可以快速搭建一个交互式界面，用于测试模型的性能和用户体验，从而加速开发迭代过程。 • 教育与教学：在教育领域，教师可以利用 Gradio 创建交互式示例，帮助学生更好地理解机器学习模型的工作原理和应用场景。
3. 安装与使用
• 安装：通过 pip 安装 Gradio，命令如下： pip install gradio• 基本使用示例：
这段代码会启动一个简单的 Web 应用，用户可以在输入框中输入名字，点击提交后会显示问候语。import gradio as gr
defgreet(name):
return"Hello " + name + "!"
demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo.launch()gradio 示例
Gradio 以其简洁易用的特点，成为机器学习和AI领域中一个非常受欢迎的工具，尤其适合需要快速创建交互式界面的场景。
什么是MCP
MCP（模型上下文协议）是一种开放协议，用于标准化应用程序向大语言模型（LLM）提供上下文的方式。将MCP视为AI应用的USB-C接口——正如USB-C为设备连接各种外设提供了标准化方案，MCP也为AI模型连接不同数据源和工具提供了标准化方法。
为什么选择MCP？
MCP帮助您在LLM之上构建智能体和复杂工作流。当LLM需要频繁集成数据和工具时，MCP能提供：
• 不断增长的预置集成清单，让LLM可直接接入 • 自由切换不同LLM供应商的灵活性 • 在自有基础设施中保障数据安全的最佳实践
总体架构
MCP采用客户端-服务器架构，宿主应用程序可连接多个服务器：
核心组件：
• MCP宿主程序：如Claude桌面版、集成开发环境（IDE）等需要通过MCP访问数据的程序 • MCP客户端：与服务器保持1:1连接的协议客户端 • MCP服务器：通过标准化模型上下文协议暴露特定功能的轻量级程序 • 本地数据源：MCP服务器可安全访问的计算机本地文件、数据库和服务 • 远程服务：MCP服务器可通过API等互联网连接的外部系统
Gradio 应用秒变 MCP Server
核心要点：只需在.launch()中设置mcp_server=True即可实现。
先决条件
如果尚未安装，请安装带有MCP扩展的Gradio：
pip install "gradio[mcp]"这将安装必要的依赖项，包括mcp包。此外，您需要一个支持使用MCP协议进行工具调用的LLM应用程序（这些被称为"MCP客户端"），例如Claude Desktop、Cursor或Cline。
什么是MCP Server？
MCP（模型控制协议）服务器是一种标准化方式，用于暴露工具以便LLM使用。工具可以为LLM提供其原生不具备的功能，例如生成图像或计算数字的质因数。
示例：计算单词中的字母数量
众所周知，LLM不太擅长计算单词中的字母数量（例如"strawberry"中有多少个"r"）。但如果我们为它们配备一个工具来帮助呢？让我们从编写一个简单的Gradio应用开始，该应用可以计算单词或短语中的字母数量：
import gradio as gr
defletter_counter(word, letter):
"""
Count the number of occurrences of a letter in a word or text.
Args:
word (str): The input text to search through
letter (str): The letter to search for
Returns:
str: A message indicating how many times the letter appears
"""
word = word.lower()
letter = letter.lower()
count = word.count(letter)
return count
demo = gr.Interface(
fn=letter_counter,
inputs=["textbox", "textbox"],
outputs="number",
title="Letter Counter",
description="Enter text and a letter to count how many times the letter appears in the text."
)
if __name__ == "__main__":
demo.launch(mcp_server=True)请注意我们做了两件事：
1. 为函数添加了详细的文档字符串， 2. 在 .launch()中设置了mcp_server=True。这就是将Gradio应用变成MCP服务器的全部所需！
现在当您运行这个应用时，它会：
1. 启动常规的Gradio网页界面 2. 启动MCP服务器 3. 在控制台打印MCP服务器URL
* Running on local URL: http://127.0.0.1:7860
* To create a public link, set `share=True` in `launch()`.
🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sseMCP服务器将通过以下地址访问：
http://127.0.0.1:7860/gradio_api/mcp/sseGradio会自动将letter_counter函数转换为可供LLM使用的MCP工具。函数的文档字符串和参数类型提示将用于生成工具描述及其参数说明。
您只需将这个URL端点添加到MCP客户端（如Claude Desktop、Cursor或Cline）中，通常只需在设置中粘贴如下配置：
{
"mcpServers":{
"gradio":{
"url":"http://your-server:port/gradio_api/mcp/sse"
}
}
}（顺带一提，您可以通过点击Gradio应用页脚的"View API"链接，然后选择"MCP"来获取可直接复制的完整配置）
客户端测试
这里以trae为例，Gradio与MCP集成的关键特性
1. 工具转换：Gradio应用中的每个API端点都会自动转换为MCP工具，包含对应的名称、描述和输入模式。查看工具和模式请访问 http://your-server:port/gradio_api/mcp/schema ，或前往Gradio应用页脚的"View API"链接，然后点击"MCP"。 2. 环境变量支持。有两种方式启用MCP服务器功能：
• 使用 mcp_server参数（如上所示）：demo.launch(mcp_server=True)• 使用环境变量： export GRADIO_MCP_SERVER=True
3. 文件处理：服务器自动处理文件数据转换，包括：
• 将base64编码字符串转换为文件数据 • 处理图像文件并以正确格式返回 • 管理临时文件存储 强烈建议将输入的图像和文件以完整URL形式传递（"http://…“或"https://…”），因为MCP客户端并不总能正确处理本地文件。
然后，就可以将以下配置添加到MCP客户端，立即开始使用该Space中的工具
{
"mcpServers":{
"gradio":{
"url":"https://abidlabs-mcp-tools.hf.space/gradio_api/mcp/sse"
}
}
}自定义MCP服务器
若需更精细的控制，您可以手动创建与托管式Gradio应用对接的MCP服务器。这种方法适用于以下场景：
• 在大型Gradio应用中选择特定端点作为工具 • 自定义工具呈现给LLM的方式（例如修改架构或描述） • 在调用工具时启动Gradio应用MCP服务器（若本地运行多个Gradio应用并希望节省内存/GPU资源） • 使用SSE之外的MCP协议
借助Gradio Python客户端和MCP Python SDK，这一目标完全可实现。以下示例展示了如何创建自定义MCP服务器，通过stdio协议连接HuggingFace Spaces上托管的多个Gradio应用：
from mcp.server.fastmcp import FastMCP
from gradio_client import Client
import sys
import io
import json
mcp = FastMCP("gradio-spaces")
clients = {}
defget_client(space_id: str) -> Client:
"""Get or create a Gradio client for the specified space."""
if space_id notin clients:
clients[space_id] = Client(space_id)
return clients[space_id]
@mcp.tool()
asyncdefgenerate_image(prompt: str, space_id: str = "ysharma/SanaSprint") -> str:
"""Generate an image using Flux.
Args:
prompt: Text prompt describing the image to generate
space_id: HuggingFace Space ID to use
"""
client = get_client(space_id)
result = client.predict(
prompt=prompt,
model_size="1.6B",
seed=0,
randomize_seed=True,
width=1024,
height=1024,
guidance_scale=4.5,
num_inference_steps=2,
api_name="/infer"
)
return result
@mcp.tool()
asyncdefrun_dia_tts(prompt: str, space_id: str = "ysharma/Dia-1.6B") -> str:
"""Text-to-Speech Synthesis.
Args:
prompt: Text prompt describing the conversation between speakers S1, S2
space_id: HuggingFace Space ID to use
"""
client = get_client(space_id)
result = client.predict(
text_input=f"""{prompt}""",
audio_prompt_input=None,
max_new_tokens=3072,
cfg_scale=3,
temperature=1.3,
top_p=0.95,
cfg_filter_top_k=30,
speed_factor=0.94,
api_name="/generate_audio"
)
return result
if __name__ == "__main__":
import sys
import io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
mcp.run(transport='stdio')该服务器提供两个工具：
1. run_dia_tts- 为给定的文本生成对话，格式为[S1]第一句话。[S2]第二句话。[S1]...2. generate_image- 使用快速文生图模型生成图像
如何在 Claude Desktop（作为 MCP 客户端）中使用此 MCP 服务器：
1. 保存代码：将代码保存为文件（例如 gradio_mcp_server.py）2. 安装依赖：运行 pip install mcp gradio-client3. 配置 Claude Desktop：
• macOS：编辑配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json• Windows：编辑配置文件 %APPDATA%\Claude\claude_desktop_config.json
在配置文件中指定您的 MCP 服务器地址即可。
{
"mcpServers":{
"gradio-spaces":{
"command":"python",
"args":[
"/absolute/path/to/gradio_mcp_server.py"
]
}
}
}4. 重启 Claude Desktop
现在，当你让 Claude 生成图像或转录音频时，它就可以调用你基于 Gradio 的工具来完成这些任务。
MCP 服务器故障排查
由于 MCP 协议仍处于早期阶段，在连接自定义 MCP 服务器时可能会遇到问题。我们推荐使用 MCP 检测工具 来测试连接并调试你的 MCP 服务器。
以下是一些可能有助于解决问题的建议：
1. 确保为函数添加了类型注解和有效的文档字符串
如前所述，Gradio 会读取函数的文档字符串（docstrings）和输入参数的类型注解，以生成工具及其参数的描述。一个有效的函数及其文档字符串应如下所示（注意 “Args:” 块及其下方带缩进的参数说明）：
defimage_orientation(image: Image.Image) -> str:
"""
Returns whether image is portrait or landscape.
Args:
image (Image.Image): The image to check.
"""
return"Portrait"if image.height > image.width else"Landscape"注意：您可以通过访问 http://your-server:port/gradio_api/mcp/schema URL 来预览为您的 MCP 服务器创建的架构。
2. 尝试将输入参数接受为 str 类型
某些 MCP 客户端无法识别数值或其他复杂类型的参数，但我们测试过的所有 MCP 客户端都接受 str 类型的输入参数。如有疑问，请将输入参数更改为 str 类型，然后在函数中将其转换为特定类型，如下例所示：
defprime_factors(n: str):
"""
Compute the prime factorization of a positive integer.
Args:
n (str): The integer to factorize. Must be greater than 1.
"""
n_int = int(n)
if n_int <= 1:
raise ValueError("Input must be an integer greater than 1.")
factors = []
while n_int % 2 == 0:
factors.append(2)
n_int //= 2
divisor = 3
while divisor * divisor <= n_int:
while n_int % divisor == 0:
factors.append(divisor)
n_int //= divisor
divisor += 2
if n_int > 1:
factors.append(n_int)
return factors
3. 确保您的 MCP 客户端支持 SSE
部分 MCP 客户端（例如 Claude Desktop）尚不支持基于 SSE 的 MCP 服务器。遇到这种情况时，您可以使用诸如 mcp-remote 这样的工具。首先安装 Node.js，然后在您的 MCP 客户端配置中添加以下内容：
{
"mcpServers":{
"gradio":{
"command":"npx",
"args":[
"mcp-remote",
"http://your-server:port/gradio_api/mcp/sse"
]
}
}
}
4. 重启您的 MCP 客户端和 MCP 服务器
某些 MCP 客户端要求您在每次更新 MCP 配置后重新启动它们。此外，如果 MCP 客户端与服务器之间的连接中断，您可能需要重启 MCP 服务器。如果其他方法都无效，请尝试同时重启 MCP 客户端和 MCP 服务器！
将本地部署的MCP服务共享给你的朋友，
1. 安装必要的包
pip install httpx[socks]2. 添加``share=True`
demo.launch(mcp_server=True, share=True)
3. 运行后得到一个免费1个星期的共享链接 成功获得共享链接
https://www.gradio.app/guides/building-mcp-server-with-gradio 翻译整理