이 가이드는 Gradio 앱을 MCP(Model Context Protocol) 서버로 실행하는 방법을 안내합니다. 핵심은 .launch()에 mcp_server=True를 넣는 것입니다. 나머지는 Gradio가 자동으로 처리합니다.

참고 문서: https://www.gradio.app/guides/building-mcp-server-with-gradio

시작하기 전에 필요 한 것

아직 Gradio가 설치되어 있지 않다면, 아래 명령어로 MCP 관련 기능까지 한 번에 설치할 수 있습니다.

pip install "gradio[mcp]"

• 위 명령으로 Gradio와 MCP 관련 의존성이 설치됩니다.
• MCP 클라이언트(예: Claude Desktop, Cursor, Cline)가 필요합니다. 이 앱들이 MCP로 도구를 호출합니다. 

Claude Desktop 설정 파일 경로

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json 

MCP가 뭔가요?

MCP는 LLM이 도구/리소스/프롬프트에 표준 방식으로 접근하도록 해주는 개방형 프로토콜입니다. 문서에서는 “AI용 USB-C” 비유로 설명합니다. 하나의 표준으로 다양한 서버(도구 제공자)와 클라이언트(IDE/데스크톱 앱)를 연결합니다. 

예시로 살펴보기 - 글자 세기 도구

LLM은 "strawberry"라는 단어에서 "r"이 몇 개인지 세는 것처럼 간단한 글자 수 세기를 잘 못하는 것으로 유명합니다. 이런 경우에 글자 수를 세는 도구를 제공하면 어떨까요? 먼저 단어나 문장에서 특정 글자가 몇 번 나오는지 세는 간단한 Gradio 앱을 만들어 보겠습니다.

import gradio as gr

def letter_counter(word, letter):
    """
    단어 또는 텍스트에서 특정 글자가 몇 번 나오는지 세어줍니다.

    Args:
        word (str): 검색할 텍스트.
        letter (str): 찾을 글자.
    Returns:
        int: 등장 횟수.
    """
    word = word.lower()
    letter = letter.lower()
    return word.count(letter)

demo = gr.Interface(
    fn=letter_counter,
    inputs=[gr.Textbox("strawberry"), gr.Textbox("r")],
    outputs=[gr.Number()],
    title="글자 세기 도구",
    description="텍스트와 글자를 넣으면 등장 횟수를 셉니다."
)

if __name__ == "__main__":
    demo.launch(mcp_server=True)

• .launch() 함수에서 mcp_server=True 로 설정합니다.
• 함수에 독스트링과 타입 힌트를 잘 달아두면, 도구 설명/스키마가 더 정확해집니다.
• 서버가 실행되면 일반 웹 UI와 함께 MCP 서버도 시작되고, 콘솔에 MCP URL이 출력됩니다.
• 기본 SSE 엔드포인트 형식은 아래와 같습니다.
  http://your-server:port/gradio_api/mcp/sse

• 이 URL은 MCP 클라이언트 설정에 그대로 넣어 쓰면 됩니다. (Gradio 앱 푸터의 View API → MCP에서 복붙용 설정을 확인할 수 있습니다.) 

MCP 클라이언트 설정 예시:

{
  "mcpServers": {
    "gradio": {
      "url": "http://your-server:port/gradio_api/mcp/sse"
    }
  }
}

MCP Client: Claude Desktop

MCP Client: Amazon Bedrock Client

Gradio × MCP

• 도구 자동 변환: Gradio 앱의 각 API 엔드포인트가 MCP 도구로 노출됩니다. 어떤 도구/스키마가 생성됐는지는 /gradio_api/mcp/schema에서 확인하거나 푸터의 View API → MCP에서 볼 수 있습니다. 
• 서버를 실행하는 두 가지 방법
  • 코드: demo.launch(mcp_server=True)
  • 환경변수: export GRADIO_MCP_SERVER=True 
• 파일/이미지 입력: 원격 환경에서는 HTTP/HTTPS 전체 URL로 전달하는 것이 호환성에 안전합니다(클라이언트별 파일 처리 차이 방지 목적). 
• Spaces에 배포 = 원격 MCP 서버: Hugging Face Spaces에 Gradio 앱을 배포하면, 바로 원격 MCP 서버로 쓸 수 있습니다. 비공개 Space를 쓰면 요청 헤더에 HF 토큰을 넣어 인증합니다. 

비공개 Space 설정 예시:

{
  "mcpServers": {
    "gradio": {
      "url": "https://<your-space>.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer <YOUR-HUGGING-FACE-TOKEN>"
      }
    }
  }
}

기존 Space를 MCP 서버로 전환하기

만약 이미 존재하는 Hugging Face Space를 MCP 서버로 사용하고 싶다면, 다음 세 가지 단계를 거쳐야 합니다.

1. 우선, 해당 Space가 본인 소유가 아니라면 Space를 복제(Duplicate)해야 합니다. 이렇게 해야 앱을 수정할 수 있습니다. 만약 원본 Space에서 GPU를 사용했다면, 복제본의 하드웨어도 원본과 동일하게 설정해야 합니다.
2. 다음으로, LLM이 도구로 호출하길 원하는 함수들에 독스트링(docstring)을 추가합니다. 독스트링은 위에 보여드린 예시 코드와 같은 형식이어야 합니다.
3. 마지막으로, .launch() 함수에 mcp_server=True를 추가하면 됩니다.

사용자 정의 MCP 서버

특정 엔드포인트만 도구화하거나, 도구 이름/스키마/설명을 세밀하게 제어하고 싶다면 커스텀 MCP 서버를 만들 수 있습니다. 예를 들어 Python SDK(FastMCP) + gradio_client 조합으로 stdio 전송 방식 서버를 띄우고, 여러 Space를 필요할 때만 호출하도록 구성하는 식입니다. 

아래 코드는 stdio 프로토콜을 사용해서 Hugging Face Spaces에 호스팅된 여러 Gradio 앱에 연결하는 사용자 정의 MCP 서버를 만드는 예시 코드입니다.

from mcp.server.fastmcp import FastMCP
from gradio_client import Client
import sys
import io
import json

mcp = FastMCP("gradio-spaces")

clients = {}
def get_client(space_id: str) -> Client:
    """지정된 Space에 대한 Gradio 클라이언트를 가져오거나 새로 생성합니다."""
    if space_id not in clients:
        clients[space_id] = Client(space_id)
    return clients[space_id]

@mcp.tool()
async def generate_image(prompt: str, space_id: str = "ysharma/SanaSprint") -> str:
    """Flux 모델을 사용해 이미지를 생성합니다.

    Args:
        prompt: 생성할 이미지를 설명하는 텍스트 프롬프트.
        space_id: 사용할 HuggingFace Space ID.
    """
    client = get_client(space_id)
    result = client.predict(
            prompt=prompt,
            model_size="1.6B",
            seed=0,
            randomize_seed=True,
            width=1024,
            height=1024,
            guidance_scale=4.5,
            num_inference_steps=2,
            api_name="/infer"
    )
    return result

@mcp.tool()
async def run_dia_tts(prompt: str, space_id: str = "ysharma/Dia-1.6B") -> str:
    """텍스트를 음성으로 합성합니다.

    Args:
        prompt: 화자 S1, S2 사이의 대화를 설명하는 텍스트 프롬프트.
        space_id: 사용할 HuggingFace Space ID.
    """
    client = get_client(space_id)
    result = client.predict(
            text_input=f"""{prompt}""",
            audio_prompt_input=None,
            max_new_tokens=3072,
            cfg_scale=3,
            temperature=1.3,
            top_p=0.95,
            cfg_filter_top_k=30,
            speed_factor=0.94,
            api_name="/generate_audio"
    )
    return result

if __name__ == "__main__":
    import sys
    import io
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

    mcp.run(transport='stdio')

이 서버는 run_dia_tts와 generate_image 두 가지 도구를 제공합니다.

• run_dia_tts: [S1]첫 번째 문장. [S2]두 번째 문장. [S1]...과 같은 형식의 대본을 받아 대화 음성을 생성합니다.
• generate_image: 빠르고 효율적인 텍스트-이미지 모델을 사용해 이미지를 생성합니다.

이 MCP 서버를 Claude Desktop(MCP 클라이언트)과 함께 사용해보겠습니다.

1. 위 코드를 파일로 저장합니다(예: gradio_mcp_server.py).
2. 필요한 라이브러리를 설치합니다: pip install mcp gradio-client
3. Claude Desktop의 설정 파일(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json)을 열어 다음과 같이 서버를 설정합니다.

{
    "mcpServers": {
        "gradio-spaces": {
            "command": "python",
            "args": [
                "/absolute/path/to/gradio_mcp_server.py"
            ]
        }
    }
}

4. Claude Desktop을 다시 시작합니다.

이제 Claude에게 이미지 생성이나 오디오 전사에 대해 질문하면, 설정한 Gradio 기반 도구들을 사용해서 이러한 작업들을 수행할 수 있게 됩니다.

클라이언트 연결 팁

• Claude Desktop: 위 경로의 설정 파일을 열어 mcpServers 항목을 추가합니다. (Developer 메뉴에서 편집 지원) 
• SSE 미지원 클라이언트 브리지: 일부 클라이언트가 원격 HTTP+SSE를 직접 못 붙일 때는 mcp-remote를 브리지로 씁니다. Node.js가 필요하며, npx mcp-remote <SSE URL> 형식으로 연결합니다. 
• 프로토콜: HTTP+SSE 클라이언트는 Accept: text/event-stream를 사용합니다. (MCP는 HTTP/stdio 등 복수 전송을 지원) 

MCP 서버 문제 해결 팁

MCP 프로토콜은 아직 초기 단계에 있어, 직접 구축한 MCP 서버에 연결할 때 문제가 발생할 수도 있습니다. 일반적으로는 MCP Inspector Tool을 사용하여 연결 상태를 확인하고 디버깅하는 것을 추천합니다.

다음은 문제 해결에 도움이 될 수 있는 몇 가지 팁입니다.

1. 타입 힌트와 독스트링 확인

함수에 타입 힌트(type hint)와 유효한 독스트링(docstring)이 올바르게 작성되었는지 확인해야 합니다.

앞서 언급했듯이, Gradio는 함수 독스트링과 입력 인수의 타입 힌트를 읽어 도구(tool)와 매개변수(parameter)에 대한 설명을 생성합니다. 유효한 함수와 독스트링의 예시는 다음과 같습니다. (특히 "Args:" 블록 아래에 매개변수 이름이 올바르게 들여쓰기 되었는지 주목해야 합니다.)

def image_orientation(image: Image.Image) -> str:
    """
    이미지가 세로 방향인지 가로 방향인지 알려줍니다.

    Args:
        image (Image.Image): 확인할 이미지.
    """
    return "Portrait" if image.height > image.width else "Landscape"

팁: http://your-server:port/gradio_api/mcp/schema URL에 방문하면, 해당 MCP 서버를 위해 생성된 스키마(schema)를 미리 확인할 수 있습니다.

2. 입력 인수를 문자열(str) 타입으로 처리

일부 MCP 클라이언트는 숫자나 다른 복잡한 타입의 매개변수를 제대로 인식하지 못할 수 있습니다. 하지만 Hugging Face에서 테스트한 모든 MCP 클라이언트는 str 타입의 입력 매개변수는 안정적으로 처리했다고 합니다.

확실하지 않은 경우에는, 입력 매개변수 타입을 우선 str로 지정하고 함수 내부에서 필요한 타입(예: 정수)으로 변환하여 사용하는 방식을 권장합니다. 다음은 관련 예시입니다.

def prime_factors(n: str):
    """
    양의 정수의 소인수 분해를 계산합니다.

    Args:
        n (str): 소인수 분해할 정수. 1보다 커야 합니다.
    """
    n_int = int(n) # 문자열을 정수로 변환
    if n_int <= 1:
        raise ValueError("입력은 1보다 큰 정수여야 합니다.")

    factors = []
    while n_int % 2 == 0:
        factors.append(2)
        n_int //= 2

    divisor = 3
    while divisor * divisor <= n_int:
        while n_int % divisor == 0:
            factors.append(divisor)
            n_int //= divisor
        divisor += 2

    if n_int > 1:
        factors.append(n_int)

    return factors

3. 클라이언트의 SSE 지원 여부 확인

MCP 클라이언트가 SSE(Server-Sent Events) 방식을 지원하는지 확인해야 합니다.

일부 MCP 클라이언트는 아직 SSE 기반의 MCP 서버를 지원하지 않을 수 있습니다. 이러한 경우에는 mcp-remote와 같은 도구를 활용할 수 있습니다. 먼저 Node.js를 설치한 후, MCP 클라이언트 설정에 다음 내용을 추가합니다.

{
  "mcpServers": {
    "gradio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-server:port/gradio_api/mcp/sse"
      ]
    }
  }
}

4. 클라이언트 및 서버 재시작

MCP 클라이언트와 MCP 서버를 모두 다시 시작해보는 것을 추천합니다.

일부 MCP 클라이언트는 MCP 설정을 업데이트할 때마다 프로그램을 다시 시작해야 합니다. 또한 때때로 클라이언트와 서버 간의 연결이 끊어졌을 때 서버를 재시작해야 할 수도 있습니다. 다른 모든 방법이 효과가 없다면, MCP 클라이언트와 서버를 모두 다시 시작하는 것이 마지막 해결 방법이 될 수 있습니다.

더 읽어보기

• Gradio 공식 가이드: Building an MCP Server with Gradio
• Hugging Face Blog: How to Build an MCP Server with Gradio
• MCP 개요: Anthropic 문서
• MCP 공식 사이트: 전송(HTTP+SSE/stdio)과 클라이언트 연결 가이드. 
• Claude Desktop 연결 가이드: 로컬/원격 서버 설정 경로. 
• mcp-remote: 원격 SSE 서버를 로컬 MCP처럼 붙이는 브리지. 

마무리

정리하면, mcp_server=True 한 줄로 Gradio 앱을 MCP 서버로 노출할 수 있습니다. 필요하면 Spaces에 배포해 원격 서버로 쓰고, 클라이언트 설정에 URL만 등록하면 됩니다.

Gradio로 MCP 서버를 구축할 때의 가장 큰 장점은 단순함과 자동화입니다.

• 개발자가 기존 Python 함수에 타입 힌트(type hints)와 독스트링(docstring)만 정확하게 작성해두면, Gradio가 이를 읽어 MCP 표준 규격(스키마)을 자동으로 생성합니다. 복잡한 API 명세를 별도로 만들 필요가 없습니다.
• 이미 Gradio 인터페이스로 구축된 수많은 머신러닝 데모나 유틸리티 함수를 거의 수정 없이 즉시 MCP '도구(Tool)'로 노출시킬 수 있습니다.
• ML 엔지니어나 데이터 과학자가 복잡한 백엔드 서버 구축 없이도, 익숙한 Python과 Gradio 환경에서 단 몇 줄의 코드(app.serve_mcp())만으로 LLM이 사용할 수 있는 도구를 만들 수 있습니다.
• 아이디어가 떠올랐을 때 LLM과 실제 작동하는 함수를 연동하는 프로토타이핑 속도가 획기적으로 빨라졌습니다.
• 이 기능 덕분에 Gradio는 단순한 UI 데모 도구를 넘어, LLM 에이전트를 위한 강력한 '백엔드 도구 허브'이자 '툴킷'으로 그 역할이 확장되었습니다.