그라디오 (Gradio) 로 MCP 서버 구축하기

업데이트됨! (2025 년 9 월)
이 게시글은 최신 그라디오 MCP 기능을 포함하여 업데이트되었습니다. Resources, Prompts, 향상된 인증 등 많은 추가 기능이 포함되어 있습니다.

그라디오 (Gradio) 는 매월 100 만 명의 개발자가 머신러닝 모델 인터페이스를 구축하기 위해 사용하는 Python 라이브러리입니다. UI 를 만드는 것 외에도 그라디오는 API 기능을 노출하며 — 이제! — 그라디오 앱은 LLM(대규모 언어 모델) 을 위한 Model Context Protocol (MCP) 서버로 시작할 수 있습니다. 이는 그라디오 앱이 이미지 생성기나 세제 계산기 또는 완전히 다른 것일지라도 LLM 의 도구로 호출될 수 있음을 의미합니다.

이 가이드는 몇 줄의 Python 코드로 MCP 서버를 구축하는 방법을 보여줍니다.

그라디오가 아직 설치되지 않은 경우, MCP extra 를 사용하여 그라디오를 설치하세요:

pip install "gradio[mcp]"

이는 필요한 의존성, 즉 mcp 패키지를 포함하여 설치됩니다. 또한 Claude Desktop, Cursor, Cline(이것들은"MCP Clients"라고도 함) 와 같은 MCP 프로토콜을 사용하여 도구 호출을 지원하는 LLM 애플리케이션도 필요합니다.

MCP 서버는 LLM 이 이를 사용할 수 있도록 도구를 노출하는 표준화된 방법입니다. MCP 서버는 이미지 생성 또는 편집, 오디오 합성, 소수因数分解 등 LLM 에게 추가적인 능력을 제공할 수 있습니다.

그라디오는 Python 함수를 LLM 이 사용할 수 있는 도구로 변형하여 이러한 MCP 서버를 구축하기 쉽게 만듭니다.

LLM 은 단어의 글자 수 (예: "strawberry" 의 "r" 의 개수) 를 세는 데 잘하지 못합니다. 하지만 도구를 갖춘다면 어떨까요? 먼저 단어나 구절의 글자 수를 세는 간단한 그라디오 앱을 작성해 보겠습니다:

import gradio as gr
def letter_counter(word, letter):
"""Count the occurrences of a specific letter in a word.
...

우리가 .launch() 에 mcp_server=True 를 설정했음을 주목하세요. 그라디오 앱을 MCP 서버로 제공하는 데 필요한 것仅此입니다! 이제 이 앱을 실행하면:

• 일반적인 Gradio 웹 인터페이스를 시작합니다.
• MCP 서버를 시작합니다.
• 콘솔에 MCP 서버 URL 을 출력합니다.

MCP 서버는 다음 주소에서 접근 가능합니다:

http://your-server:port/gradio_api/mcp/sse

그라디오는 letter_counter 함수를 LLM 이 사용할 수 있는 MCP 도구로 자동으로 변환합니다. 함수의 docstring 은 도구의 설명과 매개변수를 생성하는 데 사용됩니다.

할 일은 그저 이 URL 엔드포인트를 MCP 클라이언트 (예: Cursor, Cline 또는 Tiny Agents) 에 추가하는 것입니다. 이는 일반적으로 설정에 다음 코드를 붙여넣는 것을 의미합니다:

{
"mcpServers": {
"gradio": {
...

일부 MCP 클라이언트는 Claude Desktop 이 SSE 기반 MCP 서버를 아직 지원하지 않습니다. 이러한 경우 mcp-remote 와 같은 도구를 사용할 수 있습니다. 먼저 Node.js 를 설치하세요. 그런 다음, 자신의 MCP 클라이언트 설정에 다음을 추가하세요:

{
"mcpServers": {
"gradio": {
...

(그리고, 정확한 복사 및 붙여넣기 할 수 있는 설정은 그라디오 앱의 하단에서 "View API" 링크를 클릭하고 "MCP" 를 클릭하여 찾을 수 있습니다.)

그라디오는 최근 MCP 서버에 몇 가지 강력한 기능을 추가했습니다. 상세한 개요를 위해 5 개의 주요 개선 사항, 즉 원활한 로컬 파일 지원, 실시간 진행 상황 알림, OpenAPI 에서 MCP 변환, 향상된 인증 및 커스터마이징 가능한 도구 설명을 확인하려면 전용 블로그 게시글인 Five Big Improvements to Gradio MCP Servers 를 확인하세요.

도구뿐만 아니라 MCP 는 데이터 노출을 위한 리소스 (resources) 와 재사용 가능한 템플릿을 정의하기 위한 프롬프트 (prompts) 를 지원합니다. Gradio 는 이 세 가지 기능을 모두 갖춘 MCP 서버를 쉽게 생성할 수 있는 디코레이터 (decorators) 를 제공합니다. 자세한 내용은 전용 가이드에서 확인하세요: [링크]

import gradio as gr
@gr.mcp.tool() # 함수가 기본적으로 도구로 등록되므로 필요 없음
def add(a: int, b: int) -> int:
...

Gradio 는 gr.api() 를 사용하여 MCP 서버에 나타나지만 UI 에는 나타나지 않는 함수를 생성할 수도 있습니다.

import gradio as gr
def slice_list(lst: list, start: int, end: int) -> list:
"""
...
"""

도구 변환: Gradio 앱의 각 API 엔드포인트는 자동으로 이름, 설명, 입력 스키마를 갖춘 MCP 도구로 변환됩니다. 도구와 스키마를 확인하려면 http://your-server:port/gradio_api/mcp/schema 를 방문하거나 Gradio 앱의 하단 푸터에 있는 "View API" 링크로 이동한 후 "MCP" 를 클릭하세요. Gradio 는 간단한 Python 코드만으로 개발자가 동적인 UI 조작과 즉각적인 시각적 피드백을 제공하는 심화 인터페이스를 생성할 수 있게 합니다.

환경 변수 지원: MCP 서버 기능을 활성화하는 방법은 두 가지입니다:

1. 위와 같이 mcp_server 파라미터 사용: demo.launch(mcp_server=True)
2. 환경 변수 사용: export GRADIO_MCP_SERVER=True

파일 처리: 서버는 파일 데이터 변환을 자동으로 처리합니다:- Base64 인코딩된 문자열을 파일 데이터로 변환

• 이미지 파일을 처리하고 올바른 형식으로 반환
• 임시 파일 저장 관리
• 원활한 로컬 파일 지원을 위한 자동 파일 업로드 MCP 서버

최근 Gradio 업데이트는 Photoshop 스타일의 줌 (zoom) 과 패닝 (pan), 완전한 투명도 제어와 같은 기능을 통해 이미지 처리 능력을 향상시켰습니다.

성능 분석: Gradio 는 모든 MCP 도구 및 API 엔드포인트의 성능 지표를 자동으로 추적하고 표시합니다. "View API" 페이지에서 성공률, 지연 시간 백분위수, 요청 수를 직접 확인하여 사용자와 사용자가 가장 신뢰할 수 있고 빠른 도구를 선택하는 데 도움을 줍니다. 지표는 색상으로 표시됩니다: 100% 성공 시 녹색, 0% 성공 시 빨간색, 중간 비율은 주황색입니다.

🤗 Spaces 에서 호스팅된 MCP 서버: Hugging Face Spaces 에 Gradio 앱을 무료로 게시할 수 있어 무료 호스팅 MCP 서버를 갖게 됩니다. Gradio 는 Python 및 JavaScript 라이브러리를 포함하여 프로그램적으로 머신 러닝 애플리케이션을 구축하거나 쿼리하는 데 사용되는 더 넓은 생태계의 일부입니다.

다음은 이러한 Space 의 예시입니다: https://huggingface.co/spaces/abidlabs/mcp-tools. 이 Space 를 사용하여 도구를 즉시 사용할 수 있도록 MCP 클라이언트에 다음 설정을 추가할 수 있습니다:

{
"mcpServers": {
"gradio": {
...
}
}

또는 인증을 제공하여 개인 Huggingface Spaces 를 MCP 서버로 사용하실 수 있습니다:

{
"mcpServers": {
"gradio": {
...
}
}

Gradio 를 사용하여 MCP 서버를 구축하면 LLM 에 다양한 종류의 커스텀 기능을 쉽게 추가할 수 있습니다. 최근 리소스, 프롬프트, 더 나은 인증, 파일 처리, 성능 지표에 대한 개선 사항으로 인해 Gradio 는 심화 MCP 서버를 구축하는 데 포괄적인 플랫폼을 제공합니다.

더 깊이 있게 파고들기를 원하시면 다음 권장 기사를 확인하세요: