FastAPI-MCP

Uma ferramenta de configuração zero para expor automaticamente endpoints FastAPI como ferramentas MCP.

GitHub
1
Experimente este MCPPatrocinado

Documentação

fastapi-to-mcp

FastAPI-MCP

Uma ferramenta de configuração zero para expor automaticamente endpoints do FastAPI como ferramentas do Model Context Protocol (MCP).

PyPI version Python Versions FastAPI CI codecov

fastapi-mcp-usage

Recursos

  • Integração direta - Monte um servidor MCP diretamente no seu aplicativo FastAPI
  • Configuração zero necessária - basta apontá-lo para o seu aplicativo FastAPI e ele funciona
  • Descoberta automática de todos os endpoints FastAPI e conversão em ferramentas MCP
  • Preservação de esquemas dos seus modelos de requisição e de resposta
  • Preservação da documentação de todos os seus endpoints, exatamente como está no Swagger
  • Implantação flexível - Monte seu servidor MCP no mesmo aplicativo ou implante separadamente

Instalação

Recomendamos usar uv, um instalador de pacotes Python rápido:

uv add fastapi-mcp

Alternativamente, você pode instalar com pip:

pip install fastapi-mcp

Uso Básico

A maneira mais simples de usar FastAPI-MCP é adicionar um servidor MCP diretamente ao seu aplicativo FastAPI:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(
    app,

    # Optional parameters
    name="My API MCP",
    description="My API description",
    base_url="http://localhost:8000",
)

# Mount the MCP server directly to your FastAPI app
mcp.mount()

É isso! Seu servidor MCP gerado automaticamente agora está disponível em https://app.base.url/mcp.

Nota sobre base_url: Embora base_url seja opcional, é altamente recomendável fornecê-lo explicitamente. O base_url informa ao servidor MCP para onde enviar as requisições de API quando as ferramentas são chamadas. Sem ele, a biblioteca tentará determinar a URL automaticamente, o que pode não funcionar corretamente em ambientes implantados onde as URLs internas e externas diferem.

Nomeação de Ferramentas

FastAPI-MCP usa o operation_id das suas rotas FastAPI como nomes das ferramentas MCP. Quando você não especifica um operation_id, o FastAPI gera automaticamente um, mas esses podem ser enigmáticos.

Compare estas duas definições de endpoint:

# Auto-generated operation_id (something like "read_user_users__user_id__get")
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# Explicit operation_id (tool will be named "get_user_info")
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}

Para nomes de ferramentas mais claros e intuitivos, recomendamos adicionar parâmetros explícitos de operation_id às definições de rota do seu FastAPI.

Para saber mais, leia a documentação oficial do FastAPI sobre configuração avançada de operações de caminho.

Uso Avançado

FastAPI-MCP fornece várias maneiras de personalizar e controlar como seu servidor MCP é criado e configurado. Aqui estão alguns padrões de uso avançado:

Personalizando a Descrição do Esquema

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(
    app,
    name="My API MCP",
    base_url="http://localhost:8000",
    describe_all_responses=True,     # Include all possible response schemas in tool descriptions
    describe_full_response_schema=True  # Include full JSON schema in tool descriptions
)

mcp.mount()

Personalizando Endpoints Expostos

Você pode controlar quais endpoints FastAPI são expostos como ferramentas MCP usando IDs de operação ou tags do Open API:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

# Only include specific operations
mcp = FastApiMCP(
    app,
    include_operations=["get_user", "create_user"]
)

# Exclude specific operations
mcp = FastApiMCP(
    app,
    exclude_operations=["delete_user"]
)

# Only include operations with specific tags
mcp = FastApiMCP(
    app,
    include_tags=["users", "public"]
)

# Exclude operations with specific tags
mcp = FastApiMCP(
    app,
    exclude_tags=["admin", "internal"]
)

# Combine operation IDs and tags (include mode)
mcp = FastApiMCP(
    app,
    include_operations=["user_login"],
    include_tags=["public"]
)

mcp.mount()

Notas sobre filtragem:

  • Você não pode usar include_operations e exclude_operations ao mesmo tempo
  • Você não pode usar include_tags e exclude_tags ao mesmo tempo
  • Você pode combinar filtragem por operação com filtragem por tag (por exemplo, usar include_operations com include_tags)
  • Ao combinar filtros, uma abordagem gananciosa será adotada. Endpoints que corresponderem a qualquer um dos critérios serão incluídos

Implantando Separadamente do Aplicativo FastAPI Original

Você não está limitado a servir o MCP no mesmo aplicativo FastAPI do qual ele foi criado.

Você pode criar um servidor MCP a partir de um aplicativo FastAPI e montá-lo em um aplicativo diferente:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Your API app
api_app = FastAPI()
# ... define your API endpoints on api_app ...

# A separate app for the MCP server
mcp_app = FastAPI()

# Create MCP server from the API app
mcp = FastApiMCP(
    api_app,
    base_url="http://api-host:8001",  # The URL where the API app will be running
)

# Mount the MCP server to the separate app
mcp.mount(mcp_app)

# Now you can run both apps separately:
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000

Adicionando Endpoints Após a Criação do Servidor MCP

Se você adicionar endpoints ao seu aplicativo FastAPI após criar o servidor MCP, será necessário atualizar o servidor para incluí-los:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()
# ... define initial endpoints ...

# Create MCP server
mcp = FastApiMCP(app)
mcp.mount()

# Add new endpoints after MCP server creation
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
    return {"message": "Hello, world!"}

# Refresh the MCP server to include the new endpoint
mcp.setup_server()

Exemplos

Veja o diretório exemplos para exemplos completos.

Conectando-se ao Servidor MCP usando SSE

Assim que seu aplicativo FastAPI com integração MCP estiver em execução, você pode se conectar a ele com qualquer cliente MCP que suporte SSE, como o Cursor:

  1. Execute seu aplicativo.

  2. Em Cursor -> Configurações -> MCP, use a URL do seu endpoint do servidor MCP (por exemplo, http://localhost:8000/mcp) como sse.

  3. O Cursor descobrirá automaticamente todas as ferramentas e recursos disponíveis.

Conectando-se ao Servidor MCP usando mcp-proxy stdio

Se o seu cliente MCP não suportar SSE, por exemplo, o Claude Desktop:

  1. Execute seu aplicativo.

  2. Instale o mcp-proxy, por exemplo: uv tool install mcp-proxy.

  3. Adicione no arquivo de configuração MCP do Claude Desktop (claude_desktop_config.json):

No Windows:

{
  "mcpServers": {
    "my-api-mcp-proxy": {
        "command": "mcp-proxy",
        "args": ["http://127.0.0.1:8000/mcp"]
    }
  }
}

No MacOS:

{
  "mcpServers": {
    "my-api-mcp-proxy": {
        "command": "/Full/Path/To/Your/Executable/mcp-proxy",
        "args": ["http://127.0.0.1:8000/mcp"]
    }
  }
}

Encontre o caminho para o mcp-proxy executando no Terminal: which mcp-proxy.

  1. O Claude Desktop descobrirá automaticamente todas as ferramentas e recursos disponíveis

Desenvolvimento e Contribuição

Obrigado por considerar contribuir para o FastAPI-MCP! Incentivamos a comunidade a postar Issues e Pull Requests.

Antes de começar, consulte nosso Guia de Contribuição.

Comunidade

Junte-se à comunidade MCParty no Slack para se conectar com outros entusiastas do MCP, fazer perguntas e compartilhar suas experiências com o FastAPI-MCP.

Requisitos

  • Python 3.10+ (Recomendado 3.12)
  • uv

Licença

Licença MIT. Copyright (c) 2024 Tadata Inc.