Websearch MCP Server

An MCP server for web search and page fetching. Converts HTML to clean markdown using html-to-markdown (Rust-based, ~200 MB/s), cutting token usage by ~60% when LLMs consume web content.

No API keys required — search is powered by DuckDuckGo.

Token Savings

Run uv run python benchmark.py to reproduce. Results from fetching real pages:

| Page | HTML tokens | MD tokens | Saved | |------|-------------|-----------|-------| | GitHub Blog | 90,829 | 50,733 | 44% | | Hacker News | 11,884 | 4,381 | 63% | | MDN — JavaScript | 51,862 | 23,326 | 55% | | BBC News | 123,997 | 28,918 | 77% | | Go pkg — net/http | 119,994 | 60,344 | 50% | | Python docs — asyncio | 6,686 | 2,405 | 64% | | Rust Lang | 5,107 | 1,515 | 70% | | Total | 410,359 | 171,622 | 58% |

At Sonnet pricing ($3/M input tokens), that's $0.72 saved per batch of 7 pages.

Tools

| Tool | Description | |------|-------------| | websearch_search | Search the web via DuckDuckGo | | websearch_fetch_page | Fetch a URL and return content as markdown | | websearch_search_and_fetch | Search + fetch top results in one call |

`websearch_search`

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | str | required | Search query | | max_results | int | 10 | Number of results (1–20) | | region | str | "wt-wt" | Region code ("us-en", "wt-wt" for global) |

`websearch_fetch_page`

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | url | str | required | URL to fetch | | max_chars | int | 20000 | Truncate output (1,000–100,000) | | extract_metadata | bool | False | Include YAML frontmatter (title, meta tags) | | heading_style | str | "atx" | "atx" (#) or "underlined" |

`websearch_search_and_fetch`

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | str | required | Search query | | max_results | int | 3 | Pages to fetch (1–5) | | max_chars_per_page | int | 5000 | Max characters per page (1,000–50,000) |

Setup

Requires uv.

uv sync

Usage

MCP Inspector (dev)

uv run mcp dev server.py

Claude Code

claude mcp add websearch -- uv run --directory /path/to/mcp-websearch-server python server.py

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "websearch": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-websearch-server", "python", "server.py"]
    }
  }
}

Benchmark

uv run python benchmark.py

Fetches a set of real pages, counts tokens with tiktoken (cl100k_base), and reports HTML vs markdown savings with cost estimates for Sonnet and Opus pricing.

Dependencies

mcp — FastMCP framework
httpx — async HTTP client
html-to-markdown — Rust-based HTML-to-Markdown converter
ddgs — DuckDuckGo search (no API key)
truststore — system certificate store for SSL
tiktoken — token counting (dev dependency, for benchmark)

MCP Servers