Como Construir um Servidor MCP em 5 Linhas de Python

Publicado em 30 de abril de 2025

Atualização no GitHub

Upvote 202 +196

Abubakar Abid abidlabs

Seguir yuvraj sharma ysharma

Atualizado! (setembro de 2025)

Este post foi atualizado com os últimos recursos do Gradio MCP, incluindo Recursos, Prompts, autenticação aprimorada e muito mais.

Gradio é uma biblioteca Python usada por mais de 1 milhão de desenvolvedores todos os meses para construir interfaces para modelos de aprendizado de máquina. Além de apenas criar UIs, o Gradio também expõe capacidades de API e — agora! — aplicativos Gradio podem ser lançados como servidores do Protocolo de Contexto de Modelo (MCP) para LLMs. Isso significa que seu aplicativo Gradio, seja um gerador de imagens ou uma calculadora de impostos ou algo completamente diferente, pode ser chamado como uma ferramenta por um LLM.

Este guia mostrará como usar o Gradio para construir um servidor MCP em apenas algumas linhas de Python.

Pré-requisitos

Se ainda não estiver instalado, instale o Gradio com o extra MCP: pip install "gradio[mcp]". Isso instalará as dependências necessárias, incluindo o pacote mcp. Você também precisará de um aplicativo LLM que suporte chamadas de ferramentas usando o protocolo MCP, como Claude Desktop, Cursor ou Cline (conhecidos como "Clientes MCP").

Por que Construir um Servidor MCP?

Um servidor MCP é uma maneira padronizada de expor ferramentas para que possam ser usadas por LLMs. Um servidor MCP pode fornecer aos LLMs todos os tipos de capacidades adicionais, como a capacidade de gerar ou editar imagens, sintetizar áudio ou realizar cálculos específicos, como fatorar números primos. O Gradio facilita a construção desses servidores MCP, transformando qualquer função Python em uma ferramenta que os LLMs podem usar.

Exemplo: Contando Letras em uma Palavra

Os LLMs não são famosos por serem bons em contar o número de letras em uma palavra (por exemplo, o número de "r" em "morango"). Mas e se os equiparmos com uma ferramenta para ajudar? Vamos começar escrevendo um aplicativo Gradio simples que conta o número de letras em uma palavra ou frase:

import gradio as gr
def letter_counter(word, letter):
    """Conta as ocorrências de uma letra específica em uma palavra."
    return word.lower().count(letter.lower())
demo = gr.Interface(fn=letter_counter, inputs=["text", "text"], outputs="number", title="Contador de Letras", description="Conte quantas vezes uma letra aparece em uma palavra")
demo.launch(mcp_server=True)

Observe que definimos mcp_server=True em .launch(). Isso é tudo que você precisa para que seu aplicativo Gradio sirva como um servidor MCP! Agora, quando você executar este aplicativo, ele irá:

• Iniciar a interface web regular do Gradio
• Iniciar o servidor MCP
• Imprimir a URL do servidor MCP no console

O servidor MCP estará acessível em: http://your-server:port/gradio_api/mcp/sse. O Gradio converte automaticamente a função letter_counter em uma ferramenta MCP que pode ser usada por LLMs. A docstring da função é usada para gerar a descrição da ferramenta e seus parâmetros. Tudo o que você precisa fazer é adicionar este endpoint de URL ao seu Cliente MCP (por exemplo, Cursor, Cline ou Tiny Agents), o que normalmente significa colar esta configuração nas configurações:

{
    "mcpServers": {
        "gradio": {
            "url": "http://your-server:port/gradio_api/mcp/sse"
        }
    }
}

Alguns Clientes MCP, notavelmente o Claude Desktop, ainda não suportam Servidores MCP baseados em SSE. Nesses casos, você pode usar uma ferramenta como mcp-remote. Primeiro, instale o Node.js. Em seguida, adicione o seguinte à configuração do seu próprio Cliente MCP:

{
    "mcpServers": {
        "gradio": {
            "command": "npx",
            "args": ["mcp-remote", "http://your-server:port/gradio_api/mcp/sse"]
        }
    }
}

(A propósito, você pode encontrar a configuração exata para copiar e colar indo para o link "View API" no rodapé do seu aplicativo Gradio e, em seguida, clicando em "MCP").

Melhorias Recentes

O Gradio adicionou recentemente vários recursos poderosos aos servidores MCP. Para uma visão geral detalhada de cinco melhorias principais, incluindo suporte a arquivos locais sem costura, notificações de progresso em tempo real, transformação de OpenAPI para MCP, autenticação aprimorada e descrições de ferramentas personalizáveis, confira nosso post de blog dedicado: Cinco Grandes Melhorias nos Servidores MCP do Gradio.

Recursos e Prompts do MCP

Além das ferramentas, o MCP suporta recursos (para expor dados) e prompts (para definir modelos reutilizáveis). O Gradio fornece decoradores para criar facilmente servidores MCP com todas as três capacidades. Você pode ler mais em nosso guia dedicado, aqui:

import gradio as gr
@gr.mcp.tool()
def add(a: int, b: int) -> int:
    """Adiciona dois números"""
    return a + b
@gr.mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Obtém uma saudação personalizada"""
    return f"Olá, {name}!"
@gr.mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    """Gera um prompt de saudação"""
    styles = {
        "friendly": "Por favor, escreva uma saudação calorosa e amigável",
        "formal": "Por favor, escreva uma saudação formal e profissional",
        "casual": "Por favor, escreva uma saudação casual e descontraída",
    }
    return f"{styles.get(style, styles['friendly'])} para alguém chamado {name}."
demo = gr.TabbedInterface([
    gr.Interface(add, [gr.Number(value=1), gr.Number(value=2)], gr.Number()),
    gr.Interface(get_greeting, gr.Textbox("Abubakar"), gr.Textbox()),
    gr.Interface(greet_user, [gr.Textbox("Abubakar"), gr.Dropdown(choices=["friendly", "formal", "casual"] )], gr.Textbox()),
], ["Adicionar", "Obter Saudação", "Saudar Usuário"])
demo.launch(mcp_server=True)

Funções Apenas MCP

O Gradio também permite que você crie funções que aparecem apenas no servidor MCP (não na UI) usando gr.api():

import gradio as gr
def slice_list(lst: list, start: int, end: int) -> list:
    """Uma ferramenta que fatiará uma lista dada um índice de início e fim."
    return lst[start:end]
with gr.Blocks() as demo:
    gr.Markdown("Este aplicativo inclui ferramentas apenas MCP não visíveis na UI.")
    gr.api(slice_list)
demo.launch(mcp_server=True)

Principais recursos do Gradio <> MCP