🧠 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 – main.py

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

ou

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.

1. Vá para sua instância Open WebUI
2. Vá para configurações
3. Clique em Tools
4. 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.

---