Kindly Web Search MCP Server: full conversations, not just snippets

The snippet problem Kindly Web Search was built around

A search API returns a title, a link and a snippet. For a StackOverflow question that snippet is usually the question body, which is the least useful part of the page. The README makes this the central argument: an AI assistant gets the question, then has to make a second call to scrape the page, and the README states that this second call sometimes happens and sometimes does not. When it does happen, the README argues, generic scrapers return either partial content or the whole page with navigation and ads attached, which spends context on markup rather than on answers.

The project is written for people running AI coding assistants such as Claude Code, Codex, Cursor, Windsurf and Antigravity, plus agent clients including Claude Desktop, OpenClaw and Hermes. The stated goal is that a single tool call returns the question, the accepted answer, the comments and the code snippets together. That framing is honest about the target: this is not a general-purpose crawler, it is a retrieval layer tuned for the specific sites where developers actually find fixes.

Two tools and a six-step resolver chain

The server exposes exactly two tools. web_search(query, num_results=3) returns results with title, link, snippet and page_content, and get_content(url) returns page_content alone. Both fill page_content as Markdown on a best-effort basis, which is the README's own qualifier and worth taking literally.

The mechanism behind page_content is a priority chain. Before the universal HTML loader runs, each URL is matched against five specialized handlers in order: StackExchange sites through the StackExchange API, GitHub Issues through the GitHub GraphQL API, GitHub Discussions through the same GraphQL API, Wikipedia through the MediaWiki Action API, and arXiv through its Atom API with PDF-to-Markdown conversion. Anything that does not match falls through to a headless-browser loader. The Dockerfile shows that loader is nodriver driving Chromium over CDP, with no WebDriver in the image.

Search providers are selected in a documented order: Serper, then SerpBase, then Tavily, then SearXNG, then Sofya, then You.com, then Serply. The .env.example confirms this ordering in a comment. All HTTP handlers use httpx[socks], so HTTP_PROXY, HTTPS_PROXY and ALL_PROXY are honored for both HTTP and SOCKS5. Output is capped per source: STACKEXCHANGE_MAX_CHARS and GITHUB_MAX_CHARS default to 20000, WIKIPEDIA_MAX_CHARS and ARXIV_MAX_CHARS to 50000, and GITHUB_MAX_COMMENTS to 50.

Installing Kindly Web Search and running a first search

The package requires Python 3.13 or newer and builds with hatchling. The documented install path is uvx from the Git URL, which the pyproject.toml comments note re-resolves every dependency from PyPI on each start and ignores any lock file. A container path also exists.

Start by copying .env.example into your runtime environment. At least one search provider key must be present, and Serper is first in the selection order:

SERPER_API_KEY=
GITHUB_TOKEN=

GITHUB_TOKEN is optional but the README recommends it to avoid rate limits on the Issues and Discussions loaders. If you prefer not to use a hosted search API, set SEARXNG_BASE_URL to a self-hosted instance instead, and optionally narrow it with SEARXNG_LANGUAGE, SEARXNG_CATEGORIES or SEARXNG_TIME_RANGE.

Run the server over stdio for an MCP client, or over HTTP by setting the transport variables. The Dockerfile installs Chromium, runs as a non-root user, and ends with ENTRYPOINT ["mcp-web-search"], so building the image is the whole setup:

FROM python:3.13-slim

For HTTP or SSE transports, FASTMCP_HOST defaults to 127.0.0.1 and FASTMCP_PORT to 8000. Logging goes to stderr only, which keeps the stdio channel clean for MCP clients. Once connected, ask the agent for a StackOverflow URL and call get_content on it; the expected result is the full thread rendered as Markdown rather than a single question body. The examples directory contains a script, examples/script_run_mcp_tools.py, that exercises the tools directly.

Where the resolver chain breaks down

The chain is a fixed list, so anything outside it pays the headless-browser cost. A blog post, a vendor changelog or a documentation site goes through Chromium, which is slower than an API call and depends on the page rendering without a login wall. The README labels page_content best-effort, and that word covers the whole fallback tier.

Rate limits are the second constraint. GITHUB_TOKEN is optional in .env.example but the README recommends it to avoid rate limits, which means an unauthenticated deployment will hit them. STACKEXCHANGE_KEY is likewise optional and described as raising the quota, so the default StackExchange path is the throttled one. arXiv retrieval converts PDFs to Markdown and caps output at ARXIV_MAX_PAGES=30, so a long paper can be truncated before the interesting section.

Tool time budgets are configurable through KINDLY_TOOL_TOTAL_TIMEOUT_SECONDS, defaulting to 120, but .env.example warns that MCP clients may impose their own limits. A search that fans out across several providers and then loads a heavy page can exceed a client-side timeout the server never sees. If your agent needs a single fast snippet and nothing else, the specialized handlers and the browser fallback are overhead you are paying for no benefit.

Kindly Web Search versus a plain search MCP server

A conventional search MCP server is a thin wrapper over a search API: it returns links and snippets and leaves page retrieval to a separate scraping tool. That design keeps the server small and predictable, and it composes well if you already run a Playwright or Puppeteer MCP server. The cost is the extra round trip and the decision point the README complains about, where the model may or may not choose to fetch the page.

Kindly folds retrieval into the same call and adds site-specific parsers for StackExchange, GitHub Issues, GitHub Discussions, Wikipedia and arXiv. The trade-off is scope and weight. You get structured conversations without a second tool, but you also get a headless Chromium in the image, httpx[socks] as a dependency, and a provider selection order you have to configure around. A team already running a scraping MCP server plus a GitHub MCP server would be duplicating capability rather than gaining it. The README positions Kindly as replacing generic search, StackOverflow and scraping servers, and as reducing reliance on GitHub MCP servers; that replacement only makes sense if you accept the browser dependency.

Maintenance, packaging and the MIT licence

The repository is not archived and the last push was on 2026-09-08, so it is current. The project is at version 0.1.9 in pyproject.toml, which is pre-1.0 and means the tool signatures and environment variable names can move. There are no retrieved releases, so the changelog has to come from the commit history.

The pyproject.toml comments describe an unusual maintenance posture worth reading before you deploy. Dependency bounds were added to ten runtime packages, with each ceiling set to the next major of the verified version and each floor to that version's minor series, except mcp, whose floor stays at >=1.25 deliberately. The comment states these bounds were verified on 2026-09-06 in a fresh CPython 3.13 environment, importing the server module, CORSMiddleware and FastMCP on both CPython 3.13 and 3.14. It also states that no wired CI leg resolves on either version, and that because the documented uvx path re-resolves from PyPI on every start, a breaking major can arrive without a commit, a CI run or an alert. That is a real operational risk, not a hypothetical one, and it argues for pinning in your own environment.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. This is a description of the licence text, not legal advice; check how MIT interacts with your own distribution model. The repository also ships a SECURITY.md, which is the right place to look before reporting anything.

Editorial conclusion

Adopt it if your agent regularly quotes outdated API snippets or stops at a search result without reading the answers below it, and you already have a Serper, Tavily or SearXNG endpoint to point it at. Skip it if you need a zero-key search backend, because the README requires at least one provider key, or if you are unwilling to run a headless Chromium for the universal HTML fallback. Before rolling it out, check the pyproject.toml dependency ceilings against your own lock file, because the documented uvx install path re-resolves every bound from PyPI on each start.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server on GitHub