A Model Context Protocol server that gives any AI agent live web access — 11 focused tools.
Most models are frozen at their training cutoff. This server lets them search, read, and cite the live web — with quality scoring, caching, and a headless-browser fallback for tough pages.
Fast Serper-backed search with summaries, full-content fetch, and a progressive mode that refines queries across steps for deeper research.
Pull clean content from any page or PDF, read GitHub repos and OpenAPI specs, and expand sitemaps — with a Playwright fallback for hard pages.
Run a multi-source research pass and save a cited Markdown report. Results are cached so repeat lookups in a session are instant.
The upstream project is an excellent local search tool. We extended it into something you can host, share, and trust in production.
Run it as a remote server, not just local stdio — so a hosted instance can serve many clients over HTTPS.
Per-tenant bearer tokens and an OAuth resource-server layer (RFC 9728) so it can be exposed safely and even added to claude.ai.
Callers pass their own Serper key via header or query — the server never holds a global search key.
Query-intent detection, multi-stage extraction with a Playwright fallback, content-quality scoring, and clean Markdown output.
Repeat and near-duplicate lookups are de-duplicated and served from cache for speed and lower cost.
Rate limiting, a Serper circuit breaker, and output bounds keep a shared instance stable under load.
Saved research reports and OpenAPI specs come back as a stateless, signed download link (and an MCP resource_link) — the file lands on the caller's machine, no filesystem access needed.
Every capability is a Model Context Protocol tool any MCP-compatible client can call.
full-web-searchSearch the web AND fetch full page content from top results — the default when you'll actually read the results. (Snippets only? use summaries. Uncertain wording? use progressive.)
get-web-search-summariesLightweight search returning only snippets/titles/URLs — fastest when snippets are enough or you just need URLs to fetch next.
progressive-web-searchAuto-expands the query with synonyms/related terms when results are weak — for research where the right wording is uncertain. Slower (multi-stage).
get-single-web-page-contentExtract clean, readable content from a single URL (with headless-browser fallback).
get-pdf-contentDownload and extract text from a PDF document at any URL.
get-github-repo-contentPull a GitHub repository's README, structure, and key files for code-aware answers.
get-openapi-specFetch and parse an OpenAPI / Swagger spec into a structured, queryable shape.
get-website-sitemapDiscover a site's pages by reading and expanding its sitemap.
research_and_save_to_markdownRun a research pass across sources and save a cited Markdown report.
list-cached-documentsList documents already fetched and cached this session for fast reuse.
read-cached-documentRe-read a previously cached document by id without re-fetching.
get-web-search-summaries (fastest)full-web-search (default)progressive-web-search (auto-expands; slower)get-single-web-page-content / get-pdf-contentget-website-sitemap, then full-web-searchget-github-repo-content / get-openapi-specSearches can take 30–90s — use a generous client timeout. This guide is also returned as the MCP server's instructions at connect time, so your model picks the right tool automatically.
It speaks standard MCP, so it drops into virtually any AI client — and into Atlassian Forge apps through an LM Studio bridge.
Add the hosted server in one command with --transport http, or point it at your self-hosted stdio build.
Drop it into mcp.json — remote (url + headers) for the demo, or stdio (command + args + env) when self-hosting.
Add it to claude_desktop_config.json. Use mcp-remote to bridge the hosted URL if you're on a stdio-only build.
Any MCP-compatible client works — same mcp.json shape, remote or local.
Used by CogniRunner via an LM Studio bridge over Tailscale — give Jira/Confluence agents live web access.
Whichever path you pick, you bring your own Serper key (free tier at serper.dev).
Grab a demo key, then add the remote server to your client:
claude mcp add --transport http web-search https://worksmacstudio.tailfc4700.ts.net/websearch/mcp \ --header "Authorization: Bearer YOUR_DEMO_KEY" \ --header "X-Serper-Key: YOUR_SERPER_KEY" \ --header "X-GitHub-Token: YOUR_GITHUB_TOKEN"
{
"mcpServers": {
"web-search": {
"url": "https://worksmacstudio.tailfc4700.ts.net/websearch/mcp",
"headers": {
"Authorization": "Bearer YOUR_DEMO_KEY",
"X-Serper-Key": "YOUR_SERPER_KEY",
"X-GitHub-Token": "YOUR_GITHUB_TOKEN",
"X-Output-Dir": "my-folder (optional — a folder ON THE SERVER; for files on THIS machine, self-host below)"
}
}
}
}Clone, install, build — then point any client at your local stdio build. Your machine, your key, your limits.
git clone https://github.com/leanzero-srl/mcp-web-search cd mcp-web-search npm install && npm run build
{
"mcpServers": {
"web-search": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/mcp-web-search/dist/index.js"],
"env": {
"SERPER_API_KEY": "YOUR_SERPER_KEY",
"GITHUB_TOKEN": "YOUR_GITHUB_TOKEN",
"USE_SERPER_ONLY": "true",
"OUTPUT_DIR": "/ABSOLUTE/PATH/where/saved/files/go"
}
}
}
}research_and_save_to_markdown and get-openapi-spec tools write cited Markdown reports and raw API specs to disk. On the hosted demo that disk is our server — but every response now comes back with a signed download link (valid ~24h) and an MCP resource_link, so the file lands on your machine: click it, or have your agent fetch it — no filesystem access needed. You can also page the content inline with read-cached-document. To write files straight into your own project folder, self-host over stdio.SERPER_API_KEY (and optionally GITHUB_TOKEN) in the env block; over HTTP, pass X-Serper-Key and the optional X-GitHub-Token (or the ?serper_key / ?github_token query params). The GitHub token is only needed for the get-github-repo-content tool — it unlocks authenticated rate limits and private repos. Grab one at github.com/settings/tokens.Enter your email and we'll mint a demo bearer for the hosted server and email you the setup steps. It's a convenience for evaluation — self-host for anything real.
It doesn't just hand back search snippets — it researches, reads, and remembers.
Each call carries your own Serper key (X-Serper-Key header or ?serper_key) and optional GitHub token. The server stores no credentials — searches bill to your account, never ours.
It runs the exact query first, then automatically expands with synonyms and rephrasings across multiple stages until it surfaces strong results — instead of giving up after one weak attempt.
A WebKit-first headless browser pulls real page content (with a fallback for JS-heavy or blocking sites), builds research digests (entities, claims, key terms), and can save cited Markdown reports and raw OpenAPI specs to disk — returned as a signed download link (and paged back with read-cached-document).
Every search — hit or dead-end — is logged for the maintainer. On a no-results query, memory-capable coding agents get a nudge to record a better strategy, so the next attempt is smarter.
Most web-search MCPs are a thin wrapper around a search API. This one is a research engine.
Most MCPs: Most search MCPs return the search API's title + blurb.
This one: It crawls and extracts the real page text, with a headless-browser fallback for JavaScript-heavy or blocking sites — so the model reasons over substance, not summaries.
Most MCPs: Others run one query and return whatever comes back.
This one: When the first query underperforms it auto-expands — synonyms, rephrasings, staged broadening — and reports which stage worked.
Most MCPs: Results vanish into chat scrollback.
This one: Saves cited Markdown reports and raw OpenAPI specs to your workspace, delivered as a signed download link and paged back via read-cached-document — reusable across turns and sessions.
Most MCPs: Many bake in a vendor key and meter you.
This one: Searches bill to your own Serper account; the server stores no credentials and adds no markup.
Most MCPs: Generic search MCPs can't read API docs structurally.
This one: Extracts OpenAPI/Swagger specs into a clean method+path endpoint index, then lets you page the full raw spec.
Most MCPs: Static search wrappers never improve.
This one: Logs every search and nudges memory-capable agents to record what finally worked — turning dead-ends into reusable strategy.
Yes — MIT licensed, full source on GitHub. It's a fork of mrkrsl/web-search-mcp by Mark Russell, with our enhancements contributed back in the open.
Yes, your own Serper key. The free tier covers 2,500 searches. Searches bill to your account, never ours — the server holds no global key.
The hosted demo is a shared, rate-limited convenience to try it fast. Self-hosting gives you full control, your own limits, and no dependency on our server — it's the right choice for real work.
Any MCP client: Claude Code, Claude Desktop, LM Studio, Cursor, Cline, Roo, and more. Use the remote (url + headers) shape for the hosted server, or stdio (command + args + env) when self-hosting.
Yes. CogniRunner reaches it through an LM Studio bridge over Tailscale — that pattern gives Jira/Confluence agents live web access without exposing anything publicly.
MIT licensed. Self-host it, wire it into your AI client, and give your agent the live web in minutes.
Built on mrkrsl/web-search-mcp by Mark Russell · enhanced & maintained by LeanZero.