# 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](https://github.com/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](https://mpv.io/), 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:

```bash
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](https://github.com/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):

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

2. Test the server:

   ```bash
   source venv/bin/activate
   python test_mcp.py
   ```

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

   ```bash
   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):

```json
{
  "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:

```bash
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.