MCP MyZ Search MCP Server

How to use

To query the search server, run it as an MCP server and connect your client to its HTTP endpoint. By default it listens on port 3000, and you can customize the provider, port, proxy, and timeouts as needed. The server exposes a POST-based MCP endpoint at /mcp for streaming results and supports additional tools to extract links and page text.

Practical usage patterns you can try after starting the server:

- Start with the default settings and a Bing provider. Then switch providers by passing --default-provider to Bing, DuckDuckGo, or Google.

How to install

# Install Playwright browser binaries (Chromium)
npx playwright install chromium

# Start the MCP server with default settings
npx mcp-myz-search

Prerequisites you need before starting the server are Node.js and npm (or pnpm/yarn if preferred). You will also rely on Playwright to drive the browser for search results.

If you want to customize startup options, you can add parameters to the start command, for example to run through a proxy and a different port.

Additional notes

Startup options you can use include --port to set the listening port, --proxy to route browser traffic, --timeout for navigation timeouts, --profile to persist session data, and --human-wait to allow a human to solve challenges when not in headless mode.

Available search providers are bing, duckduckgo, and google. The provider defaults to bing if you do not override it.

The server reuses a single Playwright browser/context/page and serializes access to improve performance. If you encounter a challenge page, you can enable human solve with --human-wait when running in non-headless mode.

Text extraction prioritizes common structural regions like main, #content, or article, or a provided selector. If content isn’t found, you’ll receive a corresponding message.

Configuration options and startup parameters

Usage: program [options]

Options:
  --default-provider <provider>  default search provider (choices: "bing", "duckduckgo", "google", default: "bing")
  --port <number>                port number
  --proxy <proxy>                proxy server
  --timeout <ms>                 navigation timeout in ms
  --headed                       headed mode
  --channel <name>               browser channel (default: "chrome")
  --profile <dir>                persistent user data directory
  --human-wait <ms>              wait ms for human to solve challenge
  --stdio                        use stdio transport instead of HTTP
  --log-file <path>              log file path (default: stderr)
  -h, --help                     display help for command

Server parameters you can configure at startup include the port, an optional proxy, timeouts, a persistent profile directory, and an optional human-wait for solving challenges. These map to environment variables when preferred.

MCP server configuration and endpoints

The server exposes an HTTP MCP endpoint that you can call with a POST to /mcp to perform search-related actions. It includes tools to retrieve search links and extract page text.

Tools available via the MCP endpoint include:

- search-links: accepts { q, limit?, provider? } and returns { results, total } where each result includes link, title, and snippet.

- extract-page-text: accepts { url, selector? } and returns { text, isContentPage, url, message }.

Examples

# Custom port and proxy
npx mcp-myz-search --port 3100 --proxy socks5://127.0.0.1:1080

# Persistent profile with human wait for solving challenges in headed mode
npx mcp-myz-search --headed --profile ~/.myz-bing --human-wait 20000

search-links

Returns a list of search results for a query, with optional limit and provider, including links, titles, and snippets.

extract-page-text

Extracts text content from a page given a URL and optional CSS selector, indicating if the page is content-rich and returning the final URL and any messages.