MCP Utils

Um pacote Python com utilitários e auxiliares para construir servidores compatíveis com MCP, geralmente usando Flask e Redis.

GitHub

Documentação

mcp-utils

Um pacote de utilitários Python para construir servidores Model Context Protocol (MCP).

PyPI - Version

Sumário

mcp-utils

Visão Geral

mcp-utils fornece utilitários e auxiliares para construir servidores compatíveis com MCP em Python, com foco em implementações síncronas usando Flask. Este pacote é projetado para desenvolvedores que desejam implementar servidores MCP em seus aplicativos Python existentes sem a complexidade de código assíncrono.

Principais Recursos

Utilitários básicos para implementação de servidores MCP
Suporte a Server-Sent Events (SSE)
Decoradores simples para endpoints MCP
Implementação síncrona
Suporte ao protocolo HTTP
Fila de resposta com Redis
Modelos Pydantic abrangentes para o esquema MCP
Validação e documentação integradas

Instalação

pip install mcp-utils

Requisitos

Python 3.10+
Pydantic 2

Dependências Opcionais

Flask (para servidor web)
Gunicorn (para implantação em produção)
Redis (para fila de resposta)

Uso

Servidor MCP Básico

Aqui está um exemplo simples de criação de um servidor MCP:

from mcp_utils.core import MCPServer
from mcp_utils.schema import GetPromptResult, Message, TextContent, CallToolResult

# Create a basic MCP server
mcp = MCPServer("example", "1.0")

@mcp.prompt()
def get_weather_prompt(city: str) -> GetPromptResult:
    return GetPromptResult(
        description="Weather prompt",
        messages=[
            Message(
                role="user",
                content=TextContent(
                    text=f"What is the weather like in {city}?",
                ),
            )
        ],
    )

@mcp.tool()
def get_weather(city: str) -> str:
    return "sunny"

Exemplo com Flask

Para uso em produção, você pode usar um aplicativo Flask simples com o servidor MCP e suporte a Streamable HTTP a partir da versão 2025-06-18.

from flask import Flask, Response, url_for, request

# Create Flask app and MCP server with Redis queue
app = Flask(__name__)
mcp = MCPServer(
    "example",
    "1.0",
)

@app.route("/mcp", methods=["POST"])
def mcp_route():
    response = mcp.handle_message(request.get_json())
    return jsonify(response.model_dump(exclude_none=True))


if __name__ == "__main__":
    app.run(debug=True)

Exemplo de Tratamento de Transações com SQLAlchemy

Para uso em produção, você pode integrar o servidor MCP com Flask, Redis e SQLAlchemy para melhor manipulação de mensagens e gerenciamento de transações de banco de dados:

from flask import Flask, request
from sqlalchemy.orm import Session
from sqlalchemy import create_engine

# Create engine for PostgreSQL database
engine = create_engine("postgresql://user:pass@localhost/dbname")

# Create Flask app and MCP server with Redis queue
app = Flask(__name__)
mcp = MCPServer(
    "example",
    "1.0",
)

@app.route("/mcp", methods=["POST"])
def mcp_route():
    with Session(engine) as session:
        try:
            response = mcp.handle_message(request.get_json())
            session.commit()
        except:
            session.rollback()
            raise
        else:
            return jsonify(response.model_dump(exclude_none=True))


if __name__ == "__main__":
    app.run(debug=True)

Para um exemplo mais abrangente, incluindo configuração de logging e gerenciamento de sessão, consulte o aplicativo Flask de exemplo no repositório.

Executando com Gunicorn

Gunicorn é uma abordagem melhor para executar até mesmo localmente. Para executar o aplicativo com gunicorn:

from gunicorn.app.base import BaseApplication

class FlaskApplication(BaseApplication):
    def __init__(self, app, options=None):
        self.options = options or {}
        self.application = app
        super().__init__()

    def load_config(self):
        config = {
            key: value
            for key, value in self.options.items()
            if key in self.cfg.settings
        }
        for key, value in config.items():
            self.cfg.set(key.lower(), value)

    def load(self):
        return self.application


if __name__ == "__main__":
    handler = logging.StreamHandler(sys.stdout)
    formatter = logging.Formatter("[%(asctime)s] [%(levelname)s] %(name)s: %(message)s")
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    options = {
        "bind": "0.0.0.0:9000",
        "workers": 1,
        "worker_class": "gevent",
        "loglevel": "debug",
    }
    FlaskApplication(app, options).run()

Conectando com Clientes MCP

Cursor

Edite as configurações de MCP e adicione à configuração

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Claude Desktop

Até o momento deste escrito, o Claude Desktop não suporta MCP através de SSE e só suporta stdio. Para conectar o Claude Desktop a um servidor MCP, você precisará usar o mcp-proxy.

Exemplo de configuração para o Claude Desktop:

{
  "mcpServers": {
    "weather": {
      "command": "/Users/yourname/.local/bin/mcp-proxy",
      "args": ["http://127.0.0.1:9000/sse"]
    }
  }
}

Instalação via Smithery

Para instalar o MCP Proxy para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install mcp-proxy --client claude

Instalação via PyPI

A versão estável do pacote está disponível no repositório PyPI. Você pode instalá-lo usando o seguinte comando:

# Option 1: With uv (recommended)
uv tool install mcp-proxy

# Option 2: With pipx (alternative)
pipx install mcp-proxy

Uma vez instalado, você pode executar o servidor usando o comando mcp-proxy.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Projetos Relacionados

MCP Python SDK - O SDK Python assíncrono oficial para MCP
mcp-proxy - Uma ferramenta de proxy para conectar o Claude Desktop a servidores MCP

Licença

Licença MIT

Testando com MCP Inspector

O MCP Inspector é uma ferramenta útil para testar e depurar servidores MCP. Ele fornece uma interface web para inspecionar e testar endpoints de servidores MCP.

Instalação

Instale o MCP Inspector usando npm:

npm install -g @modelcontextprotocol/inspector

Uso

Inicie seu servidor MCP (por exemplo, o exemplo Flask acima)
Execute o MCP Inspector:

git clone git@github.com:modelcontextprotocol/inspector.git
cd inspector
npm run build
npm start

Abra seu navegador e navegue até http://127.0.0.1:6274/
Insira a URL do seu servidor MCP (por exemplo, http://localhost:9000/sse)
Use o inspector para:
- Alterar o tipo de transporte para SSE
- Testar conexões do servidor
- Monitorar eventos SSE
- Enviar mensagens de teste
- Depurar respostas

Esta ferramenta é particularmente útil durante o desenvolvimento para garantir que a implementação do seu servidor MCP esteja funcionando corretamente e em conformidade com a especificação do protocolo.