LM Studio Web Search MCP Server

A local MCP (Model Context Protocol) server that adds DuckDuckGo web search, image search, YouTube video search/playback, and IPTV channel search/playback to LM Studio.

What it does

• Exposes seven MCP tools:
  • web_search: text search with title, URL, and snippet
  • image_search: image search with direct image URLs and thumbnail URLs
  • video_search: YouTube video search with thumbnails, duration, uploader, and view count
  • open_video_in_browser: opens a YouTube video in the default browser
  • play_video_in_mpv: plays a YouTube video in the mpv desktop player
  • iptv_search: searches publicly available IPTV channels from iptv-org/iptv
  • play_iptv_in_mpv: plays an IPTV stream in mpv
• No API key required
• Runs entirely on your Mac

Files

File	Purpose
server.py	MCP server implementation
run.sh	Wrapper script that activates the venv and starts the server
requirements.txt	Python dependencies
test_mcp.py	Manual test script
mcp.json.example	Example LM Studio configuration

Tools

web_search

Text search via DuckDuckGo.

• Arguments:
  • query (string, required): search terms
  • max_results (integer, 1-10, default 5)

image_search

Image search via DuckDuckGo.

• Arguments:
  • query (string, required): search terms
  • max_results (integer, 1-10, default 5)
• Returns: markdown-formatted image results. Each result includes a markdown image tag ![title](image_url) plus the source page URL.

This format gives LM Studio the best chance of rendering the image inline in the chat window. If LM Studio does not render it inline, you can click the image URL to view it in a browser.

video_search

YouTube video search via yt-dlp.

:

• Arguments:
  • query (string, required): search terms
  • max_results (integer, 1-10, default 5)
  • format (string, default "markdown"): "markdown" returns explicit ![title](thumbnail) images plus clickable YouTube links; "plain" returns simple text links; "image" returns only clean thumbnail URLs.
• Returns: by default, markdown with the YouTube thumbnail image and a clickable Watch: link. This gives you the best chance of seeing a preview image and a working video URL in LM Studio.

Ask the model things like:

Find me YouTube videos about sourdough bread baking.

Or, to open a video after finding it:

Open the first video in my browser.

open_video_in_browser

Opens a YouTube URL in your default browser.

• Arguments:
  • url (string, required): the YouTube URL to open
• Returns: JSON status confirming the URL was opened or an error message.
• Only allows youtube.com, www.youtube.com, youtu.be, and m.youtube.com URLs for safety.

play_video_in_mpv

Plays a YouTube URL in mpv, a free desktop video player.

• Arguments:
  • url (string, required): the YouTube URL to play
  • size (string, default "large"): "default", "large" (1280x720), "fullscreen", or a custom geometry like "800x600" or "50%"
• Returns: JSON status confirming mpv was launched or an error message.
• Only allows YouTube URLs.
• Uses yt-dlp with the bestvideo*+bestaudio/best format so YouTube videos are played at the highest available quality.
• Requirements: mpv must be installed and available in your PATH. yt-dlp is already installed by this project, and mpv will use it automatically.

Install mpv on macOS:

brew install mpv

Use it from LM Studio:

Play the first video in mpv.

Or with a specific size:

Play the first video in mpv fullscreen.

mpv will open in its own window and start playing the YouTube video.

iptv_search

Searches publicly available IPTV channels from iptv-org/iptv.

• Arguments:
  • query (string, required): search terms, matched against channel title and category (group-title)
  • max_results (integer, 1-30, default 10)
• Returns: markdown results with the channel name, category, logo, ID, and clickable stream URL.
• Results are fetched from https://iptv-org.github.io/iptv/index.m3u.

Ask the model things like:

Find Singapore news channels on IPTV.

play_iptv_in_mpv

Plays an IPTV stream URL in mpv.

• Arguments:
  • url (string, required): the .m3u8 stream URL to play
  • size (string, default "large"): "default", "large" (1280x720), "fullscreen", or a custom geometry like "800x600" or "50%"
• Returns: JSON status confirming mpv was launched or an error message.
• Requirements: mpv must be installed.

Use it from LM Studio:

Play the first IPTV channel in mpv.

Quick start

1. Install dependencies (already done if you are reading this after setup):

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

2. Test the server:

   source venv/bin/activate
   python test_mcp.py
   

   Or use the official MCP client smoke test (this was used during setup):

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

Configure LM Studio

LM Studio 0.4.0+ supports MCP servers. You can add this server via the in-app MCP editor or by editing mcp.json directly.

In-app (recommended)

1. Open LM Studio
2. Go to Settings → MCP Servers
3. Click Add Server
4. Fill in:
   • Name: lmstudio-websearch
   • Transport: stdio
   • Command: bash
   • Arguments: /ABSOLUTE/PATH/TO/lmstudio-websearch/run.sh
5. Save and enable the server

Manual mcp.json

LM Studio's mcp.json location on macOS:

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

Add this entry (create the file if it does not exist):

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

Enable the setting

Make sure this setting is enabled in LM Studio:

• Settings → Server Settings → Allow calling servers from mcp.json

Use in chat

1. Load a tool-capable model. Qwen 3.8 27B has native tool use support in LM Studio.

2. Start a new chat.

3. Ask a question that requires current information, for example:

   What are the latest headlines today?

4. LM Studio should invoke the web_search tool, get results, and answer based on them.

Troubleshooting

Server is not listed in LM Studio

• Confirm the path in run.sh is absolute and the file is executable (chmod +x run.sh).
• Restart LM Studio after adding the server.
• Check LM Studio logs via Developer → Logs.

Model does not call the tool

• Use a model with native tool use support (Qwen, Llama 3.1/3.2, Mistral).
• Make sure Tools is enabled for the chat (right panel).
• Try explicitly asking the model to search the web.

Search returns no results

• DuckDuckGo occasionally blocks automated requests. Wait a moment and retry.
• Check your network connection.

Dependency issues

If you see import errors, reinstall dependencies:

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

Updating the search backend

To use a different text search provider (Brave, SearXNG, Bing, Google), edit server.py and replace do_text_search() with your preferred API.