FastAPI-MCP

특징

직접 통합 - MCP 서버를 FastAPI 앱에 직접 마운트합니다.
구성이 전혀 필요하지 않습니다. FastAPI 앱에 가리키기만 하면 작동합니다.
모든 FastAPI 엔드포인트의 자동 검색 및 MCP 도구로의 변환
요청 모델과 응답 모델의 스키마 보존
Swagger에 있는 것과 마찬가지로 모든 엔드포인트의 문서를 보존하세요 .
유연한 배포 - MCP 서버를 동일한 앱에 마운트하거나 별도로 배포

설치

빠른 Python 패키지 설치 프로그램인 uv 를 사용하는 것이 좋습니다.

지엑스피1

또는 pip를 사용하여 설치할 수 있습니다.

pip install fastapi-mcp

기본 사용법

FastAPI-MCP를 사용하는 가장 간단한 방법은 FastAPI 애플리케이션에 MCP 서버를 직접 추가하는 것입니다.

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()

이제 자동 생성된 MCP 서버를 https://app.base.url/mcp 에서 사용할 수 있습니다.

base_url 관련 참고 사항 : base_url 선택 사항이지만 명시적으로 지정하는 것이 좋습니다. base_url 은 도구가 호출될 때 MCP 서버에 API 요청을 전송할 위치를 알려줍니다. base_url이 없으면 라이브러리가 URL을 자동으로 결정하려고 시도하는데, 내부 URL과 외부 URL이 다른 배포 환경에서는 제대로 작동하지 않을 수 있습니다.

도구 명명

FastAPI-MCP는 FastAPI 경로의 operation_id MCP 도구 이름으로 사용합니다. operation_id 지정하지 않으면 FastAPI에서 자동으로 생성하지만, 이 이름은 모호할 수 있습니다.

다음 두 가지 엔드포인트 정의를 비교해 보세요.

# 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}

더 명확하고 직관적인 도구 이름을 위해 FastAPI 경로 정의에 명시적인 operation_id 매개변수를 추가하는 것이 좋습니다.

자세한 내용을 알아보려면 경로 작업의 고급 구성에 대한 FastAPI 공식 문서를 읽어보세요.

고급 사용법

FastAPI-MCP는 MCP 서버 생성 및 구성 방식을 사용자 지정하고 제어할 수 있는 여러 가지 방법을 제공합니다. 다음은 몇 가지 고급 사용 패턴입니다.

스키마 설명 사용자 정의

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()

노출된 엔드포인트 사용자 지정

Open API 작업 ID 또는 태그를 사용하여 어떤 FastAPI 엔드포인트가 MCP 도구로 노출되는지 제어할 수 있습니다.

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()

필터링에 대한 참고 사항:

include_operations 와 exclude_operations 동시에 사용할 수 없습니다.
include_tags 와 exclude_tags 동시에 사용할 수 없습니다.
작업 필터링을 태그 필터링과 결합할 수 있습니다(예: include_tags 와 함께 include_operations 사용)
필터를 결합할 때는 탐욕적인 접근 방식이 사용됩니다. 두 기준 중 하나와 일치하는 엔드포인트가 포함됩니다.

원래 FastAPI 앱과 별도로 배포

MCP는 생성된 동일한 FastAPI 앱에서만 제공될 수 있는 제한이 없습니다.

하나의 FastAPI 앱에서 MCP 서버를 만들고 다른 앱에 마운트할 수 있습니다.

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

MCP 서버 생성 후 엔드포인트 추가

MCP 서버를 만든 후 FastAPI 앱에 엔드포인트를 추가하는 경우 서버를 새로 고쳐서 엔드포인트를 포함해야 합니다.

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()

예시

전체 예제는 예제 디렉토리를 참조하세요.

SSE를 사용하여 MCP 서버에 연결

MCP 통합을 통한 FastAPI 앱이 실행되면 Cursor와 같은 SSE를 지원하는 모든 MCP 클라이언트를 사용하여 앱에 연결할 수 있습니다.

애플리케이션을 실행하세요.
커서 -> 설정 -> MCP에서 MCP 서버 엔드포인트의 URL(예: http://localhost:8000/mcp )을 sse로 사용합니다.
커서는 사용 가능한 모든 도구와 리소스를 자동으로 검색합니다.

mcp-proxy stdio를 사용하여 MCP 서버에 연결

MCP 클라이언트가 SSE를 지원하지 않는 경우(예: Claude Desktop):

애플리케이션을 실행하세요.
mcp-proxy를 설치합니다(예: uv tool install mcp-proxy .
Claude Desktop MCP 구성 파일( claude_desktop_config.json )에 다음을 추가합니다.

Windows의 경우:

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

MacOS의 경우:

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

터미널에서 which mcp-proxy 실행하여 mcp-proxy 경로를 찾으세요.

Claude Desktop은 사용 가능한 모든 도구와 리소스를 자동으로 검색합니다.

개발 및 기여

FastAPI-MCP에 기여해 주셔서 감사합니다! 커뮤니티에서 이슈와 풀 리퀘스트를 게시해 주시기 바랍니다.

시작하기 전에 기여 가이드를 참조하세요.

지역 사회

MCParty Slack 커뮤니티 에 가입하여 다른 MCP 애호가들과 소통하고, 질문하고, FastAPI-MCP에 대한 경험을 공유하세요.

요구 사항

Python 3.10+ (권장 3.12)
자외선