LM Studio 웹 검색 MCP 서버

LM Studio에 DuckDuckGo 웹 검색, 이미지 검색, YouTube 동영상 검색/재생, IPTV 채널 검색/재생 기능을 추가하는 로컬 MCP(Model Context Protocol) 서버입니다.

제공 기능

• 7가지 MCP 도구를 제공합니다:

  • web_search: 제목, URL, 스니펫이 포함된 텍스트 검색

  • image_search: 직접 이미지 URL과 썸네일 URL이 포함된 이미지 검색

  • video_search: 썸네일, 길이, 업로더, 조회수가 포함된 YouTube 동영상 검색

  • open_video_in_browser: 기본 브라우저에서 YouTube 동영상 열기

  • play_video_in_mpv: mpv 데스크톱 플레이어에서 YouTube 동영상 재생

  • iptv_search: iptv-org/iptv에서 공개 IPTV 채널 검색

  • play_iptv_in_mpv: mpv에서 IPTV 스트림 재생

• API 키 불필요

• Mac에서 완전히 로컬로 실행

Related MCP server: Universal MCP Server

파일

도구

web_search

DuckDuckGo를 통한 텍스트 검색.

• 인자:

  • query (문자열, 필수): 검색어

  • max_results (정수, 1-10, 기본값 5)

image_search

DuckDuckGo를 통한 이미지 검색.

• 인자:

  • query (문자열, 필수): 검색어

  • max_results (정수, 1-10, 기본값 5)

• 반환: 마크다운 형식의 이미지 검색 결과. 각 결과에는 마크다운 이미지 태그 ![title](image_url)와 출처 페이지 URL이 포함됩니다.

이 형식은 LM Studio가 채팅 창에 이미지를 인라인으로 렌더링할 가능성을 최대화합니다. LM Studio가 인라인으로 렌더링하지 못하는 경우, 이미지 URL을 클릭하여 브라우저에서 볼 수 있습니다.

video_search

yt-dlp를 통한 YouTube 동영상 검색.

• 인자:

  • query (문자열, 필수): 검색어

  • max_results (정수, 1-10, 기본값 5)

  • format (문자열, 기본값 "markdown"): "markdown"은 명시적 ![title](thumbnail) 이미지와 클릭 가능한 YouTube 링크를 반환합니다. "plain"은 일반 텍스트 링크를 반환합니다. "image"는 썸네일 URL만 반환합니다.

• 반환: 기본적으로 YouTube 썸네일 이미지와 클릭 가능한 Watch: 링크가 포함된 마크다운. 이 형식은 LM Studio에서 미리보기 이미지와 작동하는 동영상 URL을 볼 가능성을 최대화합니다.

모델에게 다음과 같이 요청해 보세요:

저에게 사워도우 빵 굽기에 관한 YouTube 동영상을 찾아줘.

또는 동영상을 찾은 후 열려면:

첫 번째 동영상을 내 브라우저에서 열어줘.

open_video_in_browser

기본 브라우저에서 YouTube URL을 엽니다.

• 인자:

  • url (문자열, 필수): 열 YouTube URL

• 반환: URL이 열렸는지 또는 오류가 발생했는지를 확인하는 JSON 상태.

• 보안을 위해 youtube.com, www.youtube.com, youtu.be, m.youtube.com URL만 허용합니다.

play_video_in_mpv

mpv에서 YouTube URL을 재생합니다. mpv는 무료 데스크톱 동영상 플레이어입니다.

• 인자:

  • url (문자열, 필수): 재생할 YouTube URL

  • size (문자열, 기본값 "large"): "default", "large" (1280x720), "fullscreen", 또는 "800x600"이나 "50%" 같은 사용자 지정 창 크기

• 반환: mpv가 실행되었는지 또는 오류가 발생했는지를 확인하는 JSON 상태.

• 보안을 위해 YouTube URL만 허용합니다.

• yt-dlp와 bestvideo*+bestaudio/best 형식을 사용하므로 YouTube 동영상이 최고 품질로 재생됩니다.

• 요구 사항: mpv가 설치되어 있고 PATH에 있어야 합니다. yt-dlp는 이 프로젝트에 이미 설치되어 있으며 mpv가 자동으로 사용합니다.

macOS에 mpv 설치:

brew install mpv

LM Studio에서 사용:

첫 번째 동영상을 mpv로 재생해줘.

또는 특정 크기로:

첫 번째 동영상을 mpv 전체 화면으로 재생해줘.

mpv는 자체 창에서 열리고 YouTube 동영상을 재생합니다.

iptv_search

iptv-org/iptv에서 공개 IPTV 채널을 검색합니다.

• 인자:

  • query (문자열, 필수): 채널 제목과 카테고리(group-title)에서 일치하는 검색어

  • max_results (정수, 1-30, 기본값 10)

• 반환: 채널 이름, 카테고리, 로고, ID, 클릭 가능한 스트림 URL이 포함된 마크다운 결과.

• 결과는 https://iptv-org.github.io/iptv/index.m3u에서 가져옵니다.

모델에게 다음과 같이 요청해 보세요:

싱가포르 뉴스 채널을 IPTV에서 찾아줘.

play_iptv_in_mpv

mpv에서 IPTV 스트림 URL을 재생합니다.

• 인자:

  • url (문자열, 필수): 재생할 .m3u8 스트림 URL

  • size (문자열, 기본값 "large"): "default", "large" (1280x720), "fullscreen", 또는 "800x600"이나 "50%" 같은 사용자 지정 창 크기

• 반환: mpv가 실행되었는지 또는 오류가 발생했는지를 확인하는 JSON 상태.

• 요구 사항: mpv가 설치되어 있고 PATH에 있어야 합니다.

LM Studio에서 사용:

첫 번째 IPTV 채널을 mpv로 재생해줘.

빠른 시작

1. 의존성 설치 (이 설정 이후에 이 내용을 읽고 있다면 이미 완료된 상태입니다):

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

2. 서버 테스트:

   source venv/bin/activate
   python test_mcp.py

   또는 공식 MCP 클라이언트 스모크 테스트 사용 (이 설정 중에 사용된 방법):

   source venv/bin/activate
   python -c "
   from mcp import ClientSession, StdioServerParameters, stdio_client
   import anyio
   params = StdioServerParameters(command='bash', args=['./run.sh'])
   async def main():
       async with stdio_client(params) as (read, write):
           async with ClientSession(read, write) as session:
               await session.initialize()
               print([t.name for t in (await session.list_tools()).tools])
               print((await session.call_tool('web_search', arguments={'query': 'today news', 'max_results': 2})).content[0].text[:500])
   anyio.run(main)
   "

LM Studio 구성

LM Studio 0.4.0 이상은 MCP 서버를 지원합니다. 앱 내 MCP 편집기 또는 mcp.json을 직접 편집하여 이 서버를 추가할 수 있습니다.

앱 내 (권장)

1. LM Studio 열기

2. 설정 → MCP 서버로 이동

3. 서버 추가 클릭

4. 다음 입력:

   • 이름: lmstudio-websearch

   • 전송: stdio

   • 명령: bash

   • 인자: /ABSOLUTE/PATH/TO/lmstudio-websearch/run.sh

5. 서버 저장 및 활성화

수동 mcp.json

macOS에서 LM Studio의 mcp.json 위치:

~/Library/Application Support/LM Studio/mcp.json

다음 항목 추가 (파일이 없으면 생성):

{
  "mcpServers": {
    "lmstudio-websearch": {
      "command": "bash",
      "args": [
        "/ABSOLUTE/PATH/TO/lmstudio-websearch/run.sh"
      ]
    }
  }
}

설정 활성화

LM Studio에서 이 설정이 활성화되어 있는지 확인하세요:

• 설정 → 서버 설정 → mcp.json에서 서버 호출 허용

채팅에서 사용

1. 도구 사용을 지원하는 모델을 로드하세요. Qwen 3.8 27B는 LM Studio에서 네이티브 도구 사용을 지원합니다.

2. 새 채팅을 시작하세요.

3. 예를 들어 최신 정보가 필요한 질문을 하세요:

   오늘의 최신 헤드라인 뉴스가 뭐야?

4. LM Studio가 web_search 도구를 호출하고 결과를 받아 답변해야 합니다.

문제 해결

서버가 LM Studio에 표시되지 않음

• run.sh의 경로가 절대 경로인지, 파일에 실행 권한이 있는지 확인하세요 (chmod +x run.sh).

• 서버를 추가한 후 LM Studio를 다시 시작하세요.

• 개발자 → 로그에서 LM Studio 로그를 확인하세요.

모델이 도구를 호출하지 않음

• 네이티브 도구 사용을 지원하는 모델을 사용하세요 (Qwen, Llama 3.1/3.2, Mistral).

• 채팅에 도구가 활성화되어 있는지 확인하세요 (오른쪽 패널).

• 모델에게 명시적으로 웹 검색을 요청해 보세요.

검색 결과 없음

• DuckDuckGo는 가끔 자동화된 요청을 차단합니다. 잠시 기다렸다가 다시 시도하세요.

• 네트워크 연결을 확인하세요.

의존성 문제

import 오류가 표시되면 의존성을 다시 설치하세요:

source venv/bin/activate
pip install -r requirements.txt

검색 백엔드 업데이트

다른 텍스트 검색 제공자(Brave, SearXNG, Bing, Google)를 사용하려면 server.py를 편집하고 do_text_search()를 원하는 API로 교체하세요.