README - 🧠 Servidor MCP com Python – Tutorial Prático by ryanbrito

Banner

🧠 Servidor MCP com Python – Tutorial Prático

Este repositório demonstra como criar um servidor MCP (Model Context Protocol) usando o SDK oficial da Microsoft em Python. O projeto mostra como definir ferramentas (@tool) que podem ser consumidas por LLMs, como ChatGPT ou modelos em ambientes como o Open WebUI.

🚀 Tecnologias utilizadas

Python 3.10+
uv – gerenciamento de ambientes e pacotes
mcp – SDK oficial MCP
mcpo – Middleware HTTP + documentação OpenAPI

⚙️ Instalação

# 1. Crie o ambiente virtual com uv
uv venv .venv
source .venv/bin/activate

# 2. Instale o SDK MCP, CLI e mcpo
uv add mcp mcp[cli] mcpo

🧩 Estrutura do Projeto

📁 projeto/
├── main.py         # Arquivo principal com o servidor MCP
├── README.md       # Este arquivo
└── .venv/          # Ambiente virtual (não versionar)

🛠️ Exemplo de Código –

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Tutorial MCP")

@mcp.tool()
def get_tutorial_summary():
    """
    Returns the summary of an MCP Server Tutorial

    :return: Um resumo textual sobre como construir um servidor MCP.
    """
    return (
        "Configure o ambiente com uv.\n"
        "Instale com: uv add mcp mcp[cli] mcpo\n"
        "Implemente funções com @tool\n"
        "Execute com mcpo\n"
        "Consuma via cliente MCP ou Open WebUI."
    )

@mcp.tool()
def somar(a: int, b: int) -> int:
    """
    Soma dois números inteiros e retorna o resultado.

    :param a: O primeiro número.
    :param b: O segundo número.
    :return: O resultado da soma entre a e b.
    """
    return a + b

if __name__ == "__main__":
    mcp.run(transport="stdio")  # Execução local

▶️ Como Executar

🔹 1. Modo Local (stdio)

.venv/bin/python main.py

mcp run main.py # Para executar o servidor de forma padrão

mcp dev main.py # Para Testar o servidor em modo desenvolvedor

mcp install main.py # Para instalar localmente no Claude Desktop

Esse modo é ideal para testes locais com a CLI do MCP.

🔹 2. Modo HTTP com `mcpo` para documentação OpenAPI e integração ao OpenWebUI

mcpo --port 8000 -- .venv/bin/python main.py

Acesse a documentação interativa em:
👉 http://localhost:8000/docs
Agora o servidor está disponível como uma API RESTful.

🤖 Integração com Open WebUI

Após iniciar o servidor com mcpo, você pode conectá-lo ao Open WebUI ou outras ferramentas LLM que suportam o protocolo MCP.

Vá para sua instância Open WebUI
Vá para configurações
Clique em Tools
Insira a URL do novo servidor MCP: http://localhost:8000

Para mais informações, clique aqui.

📘 Sobre docstrings nas funções

Cada @mcp.tool() deve conter uma docstring clara e completa, pois:

Aparece automaticamente na documentação OpenAPI.
É usada pela IA para decidir qual função usar, com base na consulta/query do usuário a IA.

🔥 Docstrings bem escritas melhoram muito a usabilidade com LLMs.

📢 Contribuições

Pull requests são bem-vindos! Fique à vontade para sugerir novas tools, melhorar exemplos ou expandir o tutorial.