Skip to content
Back to search

kindly-web-search-mcp-server

Kindly Web Search MCP Server: Web search + robust content retrieval for AI coding tools (Claude Code, Codex, Cursor, GitHub Copilot, Gemini, etc.) and AI agents (Claude Desktop, OpenClaw, Hermes, etc.). Supports Serper, Tavily, and SearXNG.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shelpuk-ai-technology-consulting--kindly-web-search-mcp-server/badge.svg)](/listings/shelpuk-ai-technology-consulting--kindly-web-search-mcp-server)

HTML

<a href="/listings/shelpuk-ai-technology-consulting--kindly-web-search-mcp-server"><img src="/api/listings/shelpuk-ai-technology-consulting--kindly-web-search-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1) Install `uvx`

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Re-open your terminal and verify:

uvx --version

2) Install a Chromium-based browser (required for `page_content`)

You need **Chrome / Chromium / Edge / Brave** installed on the same machine running your MCP client.

Note: If you skip this, specialized sources (StackOverflow/StackExchange, GitHub Issues/Discussions, Wikipedia, arXiv) will still work well. Only universal `page_content` extraction for arbitrary sites requires the browser.

macOS:

- Install Chrome, or:

brew install --cask chromium

Windows:

- Install Chrome or Edge. - If browser auto-detection fails later, you’ll need the path:

Get-Command chrome | Select-Object -ExpandProperty Source
# Common path:
# C:\Program Files\Google\Chrome\Application\chrome.exe
# If `Get-Command chrome` fails, try one of these:
# C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
# C:\Program Files\Microsoft\Edge\Application\msedge.exe

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install -y chromium
which chromium

Other Linux distros: install `chromium` (or `chromium-browser`) via your package manager.

3) Set your search API key (required)

Set **one** of these. Provider selection order is: Serper → SerpBase → Tavily → SearXNG → Sofya → You.com → Serply.

macOS / Linux:

export SERPER_API_KEY="..."
# or:
export TAVILY_API_KEY="..."
# or (You.com, key at https://you.com/platform/api-keys):
export YDC_API_KEY="..."
# or (Serply, key at https://serply.io):
export SERPLY_API_KEY="..."
# or
export APIFARE_TOKEN="..."
# or (self-hosted SearXNG):
export SEARXNG_BASE_URL="https://searx.example.org"

Windows (PowerShell):

$env:SERPER_API_KEY="..."
# or:
$env:TAVILY_API_KEY="..."
# or (You.com, key at https://you.com/platform/api-keys):
$env:YDC_API_KEY="..."
# or (Serply, key at https://serply.io):
$env:SERPLY_API_KEY="..."
# or
$env:APIFARE_TOKEN="..."
# or (self-hosted SearXNG):
$env:SEARXNG_BASE_URL="https://searx.example.org"

Optional (SearXNG): if your instance requires authentication or blocks bots, set:

export SEARXNG_HEADERS_JSON='{"Authorization":"Bearer ..."}'
export SEARXNG_USER_AGENT="Mozilla/5.0 ..."

Windows (PowerShell):

$env:SEARXNG_HEADERS_JSON='{"Authorization":"Bearer ..."}'
$env:SEARXNG_USER_AGENT="Mozilla/5.0 ..."

Optional (recommended for better GitHub Issue / PR extraction):

export GITHUB_TOKEN="..."

For public repos, a read-only token is enough (classic tokens often use `public_repo`; fine-grained tokens need repo read access).

4) Run command used by all MCP clients

uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server \
  kindly-web-search-mcp-server start-mcp-server

First-run note: the first `uvx` invocation may take 30–60 seconds while it builds the tool environment. If your MCP client times out on first start, run the command once in a terminal to “prewarm” it, then retry in your client.

Now configure your MCP client to run that command. Make sure your API keys are set in the same shell/OS environment that launches the MCP client (unless you paste them directly into the client config).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 930 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Improve AI-generated code quality by 20%
  2. **Web search + robust content retrieval for AI coding tools.**
  3. Kindly Web Search is a part of the **[Shelpuk AI Technology Consulting](https://shelpuk.com) agentic suite** – a set of tools that together improve the code quality produced by AI coding agents by **15–20%**. [Read more on Claude Code generation quality improvement](https://shelpuk.com/en/blog/how-to-increase-claude-code-generation-quality-by-20-percent/).
  4. Works with **Claude Code**, **Codex**, **Antigravity**, **Cursor**, **Windsurf**, and any agent that supports skills or MCP servers.
  5. | Component | Role |
  6. |--------------------------------------------------------------------------------------|---|
  7. | [tdd](https://github.com/Shelpuk-AI-Technology-Consulting/agent-skill-tdd) | Enforces TDD, requirements discipline, and peer review for every coding task |
  8. | [Serena](https://github.com/oraios/serena) | Semantic code navigation + persistent project memory |
  9. | **Kindly Web Search** ← you are here | Up-to-date API and package documentation via web search |
  10. | [Lad MCP Server](https://github.com/Shelpuk-AI-Technology-Consulting/lad_mcp_server) | Project-aware AI design and code review |
  11. If you like what we're building, please ⭐ **star this repo** – it's a huge motivation for us to keep going!
  12. ## How to use the suite
  13. **1. Install three MCP servers and one skill:**
  14. - [Serena](https://github.com/oraios/serena)
  15. - [Kindly Web Search](https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server)
  16. - [Lad MCP Server](https://github.com/Shelpuk-AI-Technology-Consulting/lad_mcp_server)
  17. - [tdd](https://github.com/Shelpuk-AI-Technology-Consulting/agent-skill-tdd)
  18. **2. Use the skill when requesting a feature:**
  19. Prompt your favorite AI coding agent (Claude Code, Codex, Cursor, etc.) as usual. Then just add `Follow $tdd` in the end.
  20. ```
  21. > Build [your feature description]. Follow $tdd.
  22. ```
  23. # Kindly Web Search MCP Server
  24. ![Kindly Web Search](assets/kindly_header.png)
  25. ## Why do we need another web search MCP server?
  26. Picture this: You're debugging a cryptic error in Google Cloud Batch with GPU instances. Your AI coding assistant searches the web and finds the *perfect* StackOverflow thread. Great, right? Not quite. Here's what most web search MCP servers give your AI:
  27. ```json
  28. {
  29. "title": "GCP Cloud Batch fails with the GPU instance template",
  30. "url": "https://stackoverflow.com/questions/76546453/...",
  31. "snippet": "I am trying to run a GCP Cloud Batch job with K80 GPU. The job runs for ~30 min. and then fails..."
  32. }
  33. ```
  34. The question is there, but **where are the answers?** Where are the solutions that other developers tried? The workarounds? The "this worked for me" comments?
  35. They're not there. Your AI now has to make a second call to scrape the page. Sometimes it does, sometimes it doesn't. And even when it does, most scrapers return either incomplete content or the entire webpage with navigation panels, ads, and other noise that wastes tokens and confuses the AI.
  36. ### The Real Problem
  37. At [Shelpuk AI Technology Consulting](https://shelpuk.com), we build custom AI products under a fixed-price model. Development efficiency isn't just nice to have - it's the foundation of our business. We've been using AI coding assistants since 2023 (GitHub Copilot, Cursor, Windsurf, Claude Code, Codex), and we noticed something frustrating:
  38. **When we developers face a complex bug, we don't just want to find a URL - we want to find the conversation.** We want to see what others tried, what worked, what didn't, and why. We want the GitHub Issue with all the comments. We want the StackOverflow thread with upvoted answers and follow-up discussions. We want the arXiv paper content, not just its abstract.
  39. Existing web search MCP servers are basically wrappers around search APIs. They're great at *finding* content, but terrible at *delivering* it in a way that's useful for AI coding assistants.
  40. ### What Kindly Does Differently
  41. We built Kindly Web Search because we needed our AI assistants to work the way *we* work. When searching for solutions, Kindly:
  42. ✅ **Integrates directly with APIs** for StackExchange, GitHub Issues, arXiv, and Wikipedia - presenting content in LLM-optimized formats with proper structure
  43. ✅ **Returns the full conversation** in a single call: questions, answers, comments, reactions, and metadata
  44. ✅ **Parses any webpage in real-time** using a headless browser for cutting-edge issues that were literally posted yesterday
  45. ✅ **Passes all useful content to the LLM immediately** - no need for a second scraping call
  46. ✅ **Supports multiple search providers** (Serper, SerpBase, Tavily, SearXNG, Sofya, You.com, and Serply) with intelligent fallback
  47. Now, when Claude Code or Codex searches for that GPU batch error, it gets the question *and* the answers. The code snippets. The "this fixed it for me" comments. Everything it needs to help you solve the problem - **in one call**.
  48. If you give Kindly a try or like the idea, please drop us a star on GitHub - it’s always huge motivation for us to keep improving it! ⭐️
  49. ## One MCP Server to Rule Them All
  50. Kindly eliminates the need for:
  51. ✅ Generic web search MCP servers
  52. ✅ StackOverflow MCP servers
  53. ✅ Web scraping MCP servers (Playwright, Puppeteer, etc.)
  54. It also significantly reduces reliance on GitHub MCP servers by providing structured Issue content through intelligent extraction.
  55. Kindly has been our daily companion in production work for months, saving us countless hours and improving the effectiveness of our AI coding assistants. We're excited to share it with the community!
  56. **Tools**
  57. - `web_search(query, num_results=3)` → top results with `title`, `link`, `snippet`, and `page_content` (Markdown, best-effort).
  58. - `get_content(url)` → `page_content` (Markdown, best-effort).
  59. ### Content resolver
  60. When extracting page content (`get_content` or `web_search` results), Kindly routes each URL through a priority chain of specialized handlers before falling back to the universal HTML loader:
  61. | Priority | Target | Handler | HTTP client | Proxy support |
  62. |----------|--------|---------|-------------|---------------|
  63. | 1 | StackExchange (StackOverflow, etc.) | StackExchange API | `httpx[socks]` | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` (HTTP, SOCKS5) |
  64. | 2 | GitHub Issues | GitHub GraphQL API | `httpx[socks]` | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` (HTTP, SOCKS5) |
  65. | 3 | GitHub Discussions | GitHub GraphQL API | `httpx[socks]` | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` (HTTP, SOCKS5) |
  66. | 4 | Wikipedia | MediaWiki Action API | `httpx[socks]` | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` (HTTP, SOCKS5) |
  67. | 5 | arXiv | Atom API + PDF → Markdown | `httpx[socks]` | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` (HTTP, SOCKS5) |
  68. | 6 | All other URLs | Universal HTML loader | headless Chromium (`nodriver`) | `KINDLY_CHROME_PROXY` (HTTP, SOCKS5, etc.) |
  69. All `httpx`-based handlers read standard proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`) and support both HTTP and SOCKS proxy URLs via the `socksio` dependency. The universal HTML loader uses Chromium's `--proxy-server` flag via `KINDLY_CHROME_PROXY`, which supports SOCKS5 and other schemes natively.
  70. Search uses **Serper** (primary, if configured), **SerpBase**, **Tavily**, **SearXNG**, **Sofya**, **You.com**, or **Serply**, and page extraction uses a local Chromium-based browser via `nodriver`.
  71. #### Markdown fast paths (skip the browser for doc sites)
  72. Before launching the headless browser, the universal HTML loader first tries to fetch markdown directly with one cheap `httpx` GET — returning it immediately on a hit and falling back to the browser unchanged on any miss. Two independent probes:
  73. | Probe | Env var | Default | Mechanism |
  74. |---|---|---|---|
  75. | **Suffix** | `KINDLY_MARKDOWN_SUFFIX_HOSTS` | `help.aliyun.com,www.alibabacloud.com/help` (on) | For listed hosts, request `{path}.md` — Aliyun docs serve `text/markdown` at that route. Add `host` or `host/path-prefix` entries for other `{path}.md` sites. |
  76. | **Accept** | `KINDLY_MARKDOWN_ACCEPT_PROBE` | `0` (off) | Set to `1` to request every universal-path URL with `Accept: text/markdown`. Catches supporters automatically (Cloudflare, Microsoft Learn, AWS, GitHub, … per [acceptmarkdown.com](https://acceptmarkdown.com/status)); on `text/html` the browser re-fetches (one extra request). |
  77. Both probes validate the response (`text/markdown`, ≥1 KB, non-empty after sanitize) and apply the same output cap as the browser path, so the returned markdown is consistent across paths. See `.env.example` for the full entries.
  78. ## Requirements
  79. - A search provider (priority order): `SERPER_API_KEY` (recommended) → `SERPBASE_API_KEY` (SerpBase, Google results) → `TAVILY_API_KEY` → `SEARXNG_BASE_URL` (self-hosted SearXNG) → `SOFYA_API_KEY` → `YDC_API_KEY` (You.com) → `SERPLY_API_KEY` (Serply) → `APIFARE_TOKEN` (apifare, prepaid balance)
  80. - A Chromium-based browser installed on the same machine running the MCP client (Chrome/Chromium/Edge/Brave)
  81. - Without a browser: specialized sources (StackExchange, GitHub Issues/Discussions, Wikipedia, arXiv) still work well, but universal HTML `page_content` extraction may fail for other sites.
  82. - Highly recommended: `GITHUB_TOKEN` (renders GitHub Issues in a much more LLM-friendly format: question + answers/comments + reactions/metadata; fewer rate limits)
  83. - Python 3.13+ is supported (Python 3.14 supported; optional “advanced PDF layout” extras are disabled on 3.14 because `onnxruntime` wheels may be unavailable).
  84. `GITHUB_TOKEN` can be read-only and limited to public repositories to avoid security/privacy concerns.
  85. ## Quickstart
  86. ### 1) Install `uvx`
  87. macOS / Linux:
  88. ```bash
  89. curl -LsSf https://astral.sh/uv/install.sh | sh
  90. ```
  91. Windows (PowerShell):
  92. ```powershell
  93. irm https://astral.sh/uv/install.ps1 | iex
  94. ```
  95. Re-open your terminal and verify:
  96. ```bash
  97. uvx --version
  98. ```
  99. ### 2) Install a Chromium-based browser (required for `page_content`)
  100. You need **Chrome / Chromium / Edge / Brave** installed on the same machine running your MCP client.
  101. Note: If you skip this, specialized sources (StackOverflow/StackExchange, GitHub Issues/Discussions, Wikipedia, arXiv) will still work well. Only universal `page_content` extraction for arbitrary sites requires the browser.
  102. macOS:
  103. - Install Chrome, or:
  104. ```bash
  105. brew install --cask chromium
  106. ```
  107. Windows:
  108. - Install Chrome or Edge.
  109. - If browser auto-detection fails later, you’ll need the path:
  110. ```powershell
  111. Get-Command chrome | Select-Object -ExpandProperty Source
  112. # Common path:
  113. # C:\Program Files\Google\Chrome\Application\chrome.exe
  114. # If `Get-Command chrome` fails, try one of these:
  115. # C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
  116. # C:\Program Files\Microsoft\Edge\Application\msedge.exe
  117. ```
  118. Linux (Ubuntu/Debian):
  119. ```bash
  120. sudo apt-get update
  121. sudo apt-get install -y chromium
  122. which chromium
  123. ```
  124. Other Linux distros: install `chromium` (or `chromium-browser`) via your package manager.
  125. ### 3) Set your search API key (required)
  126. Set **one** of these. Provider selection order is: Serper → SerpBase → Tavily → SearXNG → Sofya → You.com → Serply.
  127. macOS / Linux:
  128. ```bash
  129. export SERPER_API_KEY="..."
  130. # or:
  131. export TAVILY_API_KEY="..."
  132. # or (You.com, key at https://you.com/platform/api-keys):
  133. export YDC_API_KEY="..."
  134. # or (Serply, key at https://serply.io):
  135. export SERPLY_API_KEY="..."
  136. # or
  137. export APIFARE_TOKEN="..."
  138. # or (self-hosted SearXNG):
  139. export SEARXNG_BASE_URL="https://searx.example.org"
  140. ```
  141. Windows (PowerShell):
  142. ```powershell
  143. $env:SERPER_API_KEY="..."
  144. # or:
  145. $env:TAVILY_API_KEY="..."
  146. # or (You.com, key at https://you.com/platform/api-keys):
  147. $env:YDC_API_KEY="..."
  148. # or (Serply, key at https://serply.io):
  149. $env:SERPLY_API_KEY="..."
  150. # or
  151. $env:APIFARE_TOKEN="..."
  152. # or (self-hosted SearXNG):
  153. $env:SEARXNG_BASE_URL="https://searx.example.org"
  154. ```
  155. Optional (SearXNG): if your instance requires authentication or blocks bots, set:
  156. ```bash
  157. export SEARXNG_HEADERS_JSON='{"Authorization":"Bearer ..."}'
  158. export SEARXNG_USER_AGENT="Mozilla/5.0 ..."
  159. ```
  160. Windows (PowerShell):
  161. ```powershell
  162. $env:SEARXNG_HEADERS_JSON='{"Authorization":"Bearer ..."}'
  163. $env:SEARXNG_USER_AGENT="Mozilla/5.0 ..."
  164. ```
  165. Optional (recommended for better GitHub Issue / PR extraction):
  166. ```bash
  167. export GITHUB_TOKEN="..."
  168. ```
  169. For public repos, a read-only token is enough (classic tokens often use `public_repo`; fine-grained tokens need repo read access).
  170. ### 4) Run command used by all MCP clients
  171. ```bash
  172. uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server \
  173. kindly-web-search-mcp-server start-mcp-server
  174. ```
  175. First-run note: the first `uvx` invocation may take 30–60 seconds while it builds the tool environment. If your MCP client times out on first start, run the command once in a terminal to “prewarm” it, then retry in your client.
  176. Now configure your MCP client to run that command.
  177. Make sure your API keys are set in the same shell/OS environment that launches the MCP client (unless you paste them directly into the client config).
  178. ## Client setup
  179. ### Codex
  180. Set one of `SERPER_API_KEY`, `SERPBASE_API_KEY`, `TAVILY_API_KEY`, `SEARXNG_BASE_URL`, `SOFYA_API_KEY`, `YDC_API_KEY`, `SERPLY_API_KEY`, or `APIFARE_TOKEN`.
  181. CLI (no file editing) — add a local stdio MCP server:
  182. macOS / Linux (Serper):
  183. ```bash
  184. codex mcp add kindly-web-search \
  185. --env SERPER_API_KEY="$SERPER_API_KEY" \
  186. --env GITHUB_TOKEN="$GITHUB_TOKEN" \
  187. --env KINDLY_BROWSER_EXECUTABLE_PATH="$KINDLY_BROWSER_EXECUTABLE_PATH" \
  188. -- uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server \
  189. kindly-web-search-mcp-server start-mcp-server
  190. ```
  191. macOS / Linux (Tavily):
  192. ```bash
  193. codex mcp add kindly-web-search \
  194. --env TAVILY_API_KEY="$TAVILY_API_KEY" \
  195. --env GITHUB_TOKEN="$GITHUB_TOKEN" \
  196. --env KINDLY_BROWSER_EXECUTABLE_PATH="$KINDLY_BROWSER_EXECUTABLE_PATH" \
  197. -- uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server \
  198. kindly-web-search-mcp-server start-mcp-server
  199. ```
  200. If you use SearXNG, replace the provider env var above with:
  201. ```bash
  202. --env SEARXNG_BASE_URL="$SEARXNG_BASE_URL"
  203. ```
  204. Windows (PowerShell):
  205. ```powershell
  206. codex mcp add kindly-web-search `
  207. --env SERPER_API_KEY="$env:SERPER_API_KEY" `
  208. --env GITHUB_TOKEN="$env:GITHUB_TOKEN" `
  209. --env KINDLY_BROWSER_EXECUTABLE_PATH="$env:KINDLY_BROWSER_EXECUTABLE_PATH" `
  210. -- uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server `
  211. kindly-web-search-mcp-server start-mcp-server
  212. ```
  213. Windows (PowerShell, Tavily):
  214. ```powershell
  215. codex mcp add kindly-web-search `
  216. --env TAVILY_API_KEY="$env:TAVILY_API_KEY" `
  217. --env GITHUB_TOKEN="$env:GITHUB_TOKEN" `
  218. --env KINDLY_BROWSER_EXECUTABLE_PATH="$env:KINDLY_BROWSER_EXECUTABLE_PATH" `
  219. -- uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server `
  220. kindly-web-search-mcp-server start-mcp-server
  221. ```
  222. Alternative (file-based):
  223. Edit `~/.codex/config.toml`:
  224. ```toml
  225. [mcp_servers.kindly-web-search]
  226. command = "uvx"
  227. args = [
  228. "--from",
  229. "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server",
  230. "kindly-web-search-mcp-server",
  231. "start-mcp-server",
  232. ]
  233. # Forward variables from your shell/OS environment:
  234. env_vars = ["SERPER_API_KEY", "SERPBASE_API_KEY", "TAVILY_API_KEY", "SEARXNG_BASE_URL", "SOFYA_API_KEY", "YDC_API_KEY", "SERPLY_API_KEY", "APIFARE_TOKEN", "GITHUB_TOKEN", "KINDLY_BROWSER_EXECUTABLE_PATH"]
  235. startup_timeout_sec = 120.0
  236. ```
  237. ### Claude Code
  238. Set one of `SERPER_API_KEY`, `SERPBASE_API_KEY`, `TAVILY_API_KEY`, `SEARXNG_BASE_URL`, `SOFYA_API_KEY`, `YDC_API_KEY`, `SERPLY_API_KEY`, or `APIFARE_TOKEN`.
  239. CLI (no file editing) — add a local stdio MCP server:
  240. macOS / Linux (Serper):
  241. ```bash
  242. claude mcp add --transport stdio kindly-web-search \
  243. -e SERPER_API_KEY="$SERPER_API_KEY" \
  244. -e GITHUB_TOKEN="$GITHUB_TOKEN" \
  245. -e KINDLY_BROWSER_EXECUTABLE_PATH="$KINDLY_BROWSER_EXECUTABLE_PATH" \
  246. -- uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server \
  247. kindly-web-search-mcp-server start-mcp-server
  248. ```
  249. macOS / Linux (Tavily):
  250. ```bash
  251. claude mcp add --transport stdio kindly-web-search \
  252. -e TAVILY_API_KEY="$TAVILY_API_KEY" \
  253. -e GITHUB_TOKEN="$GITHUB_TOKEN" \
  254. -e KINDLY_BROWSER_EXECUTABLE_PATH="$KINDLY_BROWSER_EXECUTABLE_PATH" \
  255. -- uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server \
  256. kindly-web-search-mcp-server start-mcp-server
  257. ```
  258. If you use SearXNG, replace the provider env var above with:
  259. ```bash
  260. -e SEARXNG_BASE_URL="$SEARXNG_BASE_URL"
  261. ```
  262. Windows (PowerShell):
  263. ```powershell
  264. claude mcp add --transport stdio kindly-web-search `
  265. -e SERPER_API_KEY="$env:SERPER_API_KEY" `
  266. -e GITHUB_TOKEN="$env:GITHUB_TOKEN" `
  267. -e KINDLY_BROWSER_EXECUTABLE_PATH="$env:KINDLY_BROWSER_EXECUTABLE_PATH" `
  268. -- uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server `
  269. kindly-web-search-mcp-server start-mcp-server
  270. ```
  271. Windows (PowerShell, Tavily):
  272. ```powershell
  273. claude mcp add --transport stdio kindly-web-search `
  274. -e TAVILY_API_KEY="$env:TAVILY_API_KEY" `
  275. -e GITHUB_TOKEN="$env:GITHUB_TOKEN" `
  276. -e KINDLY_BROWSER_EXECUTABLE_PATH="$env:KINDLY_BROWSER_EXECUTABLE_PATH" `
  277. -- uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server `
  278. kindly-web-search-mcp-server start-mcp-server
  279. ```
  280. Note: On current Claude Code versions, keep the server name immediately after `--transport stdio` and before `-e/--env` flags. Tested with Claude Code `2.0.76`.
  281. If Claude Code times out while starting the server, set a 120s startup timeout (milliseconds):
  282. macOS / Linux:
  283. ```bash
  284. export MCP_TIMEOUT=120000
  285. ```
  286. Windows (PowerShell):
  287. ```powershell
  288. $env:MCP_TIMEOUT="120000"
  289. ```
  290. Alternative (file-based):
  291. Create/edit `.mcp.json` (project scope; recommended for teams):
  292. ```json
  293. {
  294. "mcpServers": {
  295. "kindly-web-search": {
  296. "command": "uvx",
  297. "args": [
  298. "--from",
  299. "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server",
  300. "kindly-web-search-mcp-server",
  301. "start-mcp-server"
  302. ],
  303. "env": {
  304. "SERPER_API_KEY": "${SERPER_API_KEY}",
  305. "TAVILY_API_KEY": "${TAVILY_API_KEY}",
  306. "SEARXNG_BASE_URL": "${SEARXNG_BASE_URL}",
  307. "GITHUB_TOKEN": "${GITHUB_TOKEN}",
  308. "KINDLY_BROWSER_EXECUTABLE_PATH": "${KINDLY_BROWSER_EXECUTABLE_PATH}"
  309. }
  310. }
  311. }
  312. }
  313. ```
  314. ### Gemini CLI
  315. Set one of `SERPER_API_KEY`, `SERPBASE_API_KEY`, `TAVILY_API_KEY`, `SEARXNG_BASE_URL`, `SOFYA_API_KEY`, `YDC_API_KEY`, `SERPLY_API_KEY`, or `APIFARE_TOKEN`.
  316. Edit `~/.gemini/settings.json` (or `.gemini/settings.json` in a project):
  317. ```json
  318. {
  319. "mcpServers": {
  320. "kindly-web-search": {
  321. "command": "uvx",
  322. "args": [
  323. "--from",
  324. "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server",
  325. "kindly-web-search-mcp-server",
  326. "start-mcp-server"
  327. ],
  328. "env": {
  329. "SERPER_API_KEY": "$SERPER_API_KEY",
  330. "TAVILY_API_KEY": "$TAVILY_API_KEY",
  331. "SEARXNG_BASE_URL": "$SEARXNG_BASE_URL",
  332. "GITHUB_TOKEN": "$GITHUB_TOKEN",
  333. "KINDLY_BROWSER_EXECUTABLE_PATH": "$KINDLY_BROWSER_EXECUTABLE_PATH"
  334. },
  335. "timeout": 120000
  336. }
  337. }
  338. }
  339. ```
  340. ### OpenClaw
  341. Set one of `SERPER_API_KEY`, `SERPBASE_API_KEY`, `TAVILY_API_KEY`, `SEARXNG_BASE_URL`, `SOFYA_API_KEY`, `YDC_API_KEY`, `SERPLY_API_KEY`, or `APIFARE_TOKEN`.
  342. If `mcporter` is not installed yet: `npm i -g mcporter`.
  343. mcporter docs: <https://github.com/steipete/mcporter/blob/main/docs/config.md>
  344. CLI (no file editing) — `mcporter` (recommended):
  345. ```bash
  346. # Replace `$...` vars with real values, or export them in your shell first.
  347. mcporter config add kindly-search \
  348. --scope home \
  349. --command "uvx --from git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server kindly-web-search-mcp-server start-mcp-server" \
  350. --env SERPER_API_KEY="$SERPER_API_KEY" \
  351. --env TAVILY_API_KEY="$TAVILY_API_KEY" \
  352. --env SEARXNG_BASE_URL="$SEARXNG_BASE_URL" \
  353. --env GITHUB_TOKEN="$GITHUB_TOKEN" \
  354. --env KINDLY_BROWSER_EXECUTABLE_PATH="$KINDLY_BROWSER_EXECUTABLE_PATH"
  355. ```
  356. This writes to `~/.mcporter/mcporter.json` (`--scope home`).
  357. You can replace `kindly-search` with any server name you prefer.
  358. Verify:
  359. ```bash
  360. mcporter config get kindly-search
  361. ```
  362. Alternative (file-based):
  363. Edit mcporter config (`~/.mcporter/mcporter.json`, or `config/mcporter.json` if you use project scope) and add this under `mcpServers`:
  364. ```json
  365. {
  366. "mcpServers": {
  367. "kindly-search": {
  368. "command": "uvx",
  369. "args": [
  370. "--from",
  371. "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server",
  372. "kindly-web-search-mcp-server",
  373. "start-mcp-server"
  374. ],
  375. "env": {
  376. "SERPER_API_KEY": "PASTE_SERPER_KEY_OR_LEAVE_EMPTY",
  377. "TAVILY_API_KEY": "PASTE_TAVILY_KEY_OR_LEAVE_EMPTY",
  378. "SEARXNG_BASE_URL": "PASTE_SEARXNG_URL_OR_LEAVE_EMPTY",
  379. "GITHUB_TOKEN": "PASTE_GITHUB_TOKEN_OR_LEAVE_EMPTY",
  380. "KINDLY_BROWSER_EXECUTABLE_PATH": "PASTE_IF_NEEDED"
  381. }
  382. }
  383. }
  384. }
  385. ```
  386. Do **not** add root-level `mcpServers` to `~/.openclaw/openclaw.json` (OpenClaw config uses strict schema validation and unknown keys are rejected).
  387. If OpenClaw is already running and doesn’t pick up the new server, restart/reload the gateway:
  388. ```bash
  389. openclaw gateway restart
  390. ```
  391. ### Antigravity (Google IDE)
  392. Set one of `SERPER_API_KEY`, `SERPBASE_API_KEY`, `TAVILY_API_KEY`, `SEARXNG_BASE_URL`, `SOFYA_API_KEY`, `YDC_API_KEY`, `SERPLY_API_KEY`, or `APIFARE_TOKEN`.
  393. In Antigravity, open the MCP store, then:
  394. 1. Click **Manage MCP Servers**
  395. 2. Click **View raw config** (this opens `mcp_config.json`)
  396. 3. Add the server config under `mcpServers`, save, then go back and click **Refresh**
  397. Paste this into your `mcpServers` object (don’t overwrite other servers):
  398. ```json
  399. {
  400. "kindly-web-search": {
  401. "command": "uvx",
  402. "args": [
  403. "--from",
  404. "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server",
  405. "kindly-web-search-mcp-server",
  406. "start-mcp-server"
  407. ],
  408. "env": {
  409. "SERPER_API_KEY": "PASTE_SERPER_KEY_OR_LEAVE_EMPTY",
  410. "TAVILY_API_KEY": "PASTE_TAVILY_KEY_OR_LEAVE_EMPTY",
  411. "SEARXNG_BASE_URL": "PASTE_SEARXNG_URL_OR_LEAVE_EMPTY",
  412. "GITHUB_TOKEN": "PASTE_GITHUB_TOKEN_OR_LEAVE_EMPTY",
  413. "KINDLY_BROWSER_EXECUTABLE_PATH": "PASTE_IF_NEEDED"
  414. }
  415. }
  416. }
  417. ```
  418. If Antigravity can’t find `uvx`, replace `"uvx"` with the absolute path (`which uvx` on macOS/Linux, `where uvx` on Windows).
  419. Make sure at least one of `SERPER_API_KEY` / `SERPBASE_API_KEY` / `TAVILY_API_KEY` / `SEARXNG_BASE_URL` / `SOFYA_API_KEY` / `YDC_API_KEY` / `SERPLY_API_KEY` / `APIFARE_TOKEN` is non-empty.
  420. If the first start is slow, run the `uvx` command from Quickstart once in a terminal to prebuild the environment, then click **Refresh**.
  421. Don’t commit/share `mcp_config.json` if it contains API keys.
  422. ### Cursor
  423. Set one of `SERPER_API_KEY`, `SERPBASE_API_KEY`, `TAVILY_API_KEY`, `SEARXNG_BASE_URL`, `SOFYA_API_KEY`, `YDC_API_KEY`, `SERPLY_API_KEY`, or `APIFARE_TOKEN`.
  424. Startup timeout: Cursor does not currently expose a per-server startup timeout setting. If the first run is slow, run the `uvx` command from Quickstart once in a terminal to prebuild the tool environment, then restart Cursor.
  425. Create `.cursor/mcp.json`:
  426. ```json
  427. {
  428. "mcpServers": {
  429. "kindly-web-search": {
  430. "type": "stdio",
  431. "command": "uvx",
  432. "args": [
  433. "--from",
  434. "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server",
  435. "kindly-web-search-mcp-server",
  436. "start-mcp-server"
  437. ],
  438. "env": {
  439. "SERPER_API_KEY": "${env:SERPER_API_KEY}",
  440. "TAVILY_API_KEY": "${env:TAVILY_API_KEY}",
  441. "SEARXNG_BASE_URL": "${env:SEARXNG_BASE_URL}",
  442. "GITHUB_TOKEN": "${env:GITHUB_TOKEN}",
  443. "KINDLY_BROWSER_EXECUTABLE_PATH": "${env:KINDLY_BROWSER_EXECUTABLE_PATH}"
  444. }
  445. }
  446. }
  447. }
  448. ```
  449. ### Claude Desktop
  450. Edit `claude_desktop_config.json`:
  451. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  452. - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
  453. Note: values in this file are literal strings. Don’t commit this file or share it.
  454. Startup timeout: Claude Desktop does not expose a per-server startup timeout setting. If the first run is slow, run the `uvx` command from Quickstart once in a terminal to prebuild the tool environment, then restart Claude Desktop.
  455. ```json
  456. {
  457. "mcpServers": {
  458. "kindly-web-search": {
  459. "command": "uvx",
  460. "args": [
  461. "--from",
  462. "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server",
  463. "kindly-web-search-mcp-server",
  464. "start-mcp-server"
  465. ],
  466. "env": {
  467. "SERPER_API_KEY": "PASTE_SERPER_KEY_OR_LEAVE_EMPTY",
  468. "TAVILY_API_KEY": "PASTE_TAVILY_KEY_OR_LEAVE_EMPTY",
  469. "SEARXNG_BASE_URL": "PASTE_SEARXNG_URL_OR_LEAVE_EMPTY",
  470. "GITHUB_TOKEN": "PASTE_GITHUB_TOKEN_OR_LEAVE_EMPTY",
  471. "KINDLY_BROWSER_EXECUTABLE_PATH": "PASTE_IF_NEEDED"
  472. }
  473. }
  474. }
  475. }
  476. ```
  477. ### GitHub Copilot / Microsoft Copilot (VS Code)
  478. Most secure option: uses interactive prompts, so secrets don’t need to be stored in the file.
  479. Startup timeout: VS Code currently does not expose a per-server startup timeout setting for MCP servers. If the first run is slow, run the `uvx` command from Quickstart once in a terminal to prebuild the tool environment, then restart VS Code.
  480. Create `.vscode/mcp.json`:
  481. ```json
  482. {
  483. "servers": {
  484. "kindly-web-search": {
  485. "type": "stdio",
  486. "command": "uvx",
  487. "args": [
  488. "--from",
  489. "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server",
  490. "kindly-web-search-mcp-server",
  491. "start-mcp-server"
  492. ],
  493. "env": {
  494. "SERPER_API_KEY": "${input:serper-api-key}",
  495. "TAVILY_API_KEY": "${input:tavily-api-key}",
  496. "SEARXNG_BASE_URL": "${input:searxng-base-url}",
  497. "GITHUB_TOKEN": "${input:github-token}",
  498. "KINDLY_BROWSER_EXECUTABLE_PATH": "${input:browser-path}"
  499. }
  500. }
  501. },
  502. "inputs": [
  503. { "id": "serper-api-key", "type": "promptString", "description": "Serper API key (optional if using Tavily or SearXNG)" },
  504. { "id": "tavily-api-key", "type": "promptString", "description": "Tavily API key (optional if using Serper or SearXNG)" },
  505. { "id": "searxng-base-url", "type": "promptString", "description": "SearXNG base URL (optional if using Serper or Tavily)" },
  506. { "id": "github-token", "type": "promptString", "description": "GitHub token (recommended)" },
  507. { "id": "browser-path", "type": "promptString", "description": "Browser binary path (only if needed)" }
  508. ]
  509. }
  510. ```
  511. ## Browser path (only if auto-detection fails)
  512. Set `KINDLY_BROWSER_EXECUTABLE_PATH` to your browser binary.
  513. macOS (Google Chrome):
  514. ```bash
  515. export KINDLY_BROWSER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  516. ```
  517. macOS (Homebrew Chromium):
  518. ```bash
  519. export KINDLY_BROWSER_EXECUTABLE_PATH="/Applications/Chromium.app/Contents/MacOS/Chromium"
  520. ```
  521. Linux:
  522. ```bash
  523. export KINDLY_BROWSER_EXECUTABLE_PATH="$(command -v chromium || command -v chromium-browser)"
  524. ```
  525. Windows (PowerShell):
  526. ```powershell
  527. $env:KINDLY_BROWSER_EXECUTABLE_PATH="C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
  528. ```
  529. ## Chromium proxy (optional)
  530. Set `KINDLY_CHROME_PROXY` to route all headless Chromium traffic (used for `page_content` extraction) through a proxy server. The value is passed directly as Chromium's `--proxy-server` flag.
  531. Supported schemes: `http://`, `https://`, `socks5://`, `socks4://`.
  532. ```bash
  533. export KINDLY_CHROME_PROXY="socks5://127.0.0.1:1080"
  534. ```
  535. When running in Docker, use `host.docker.internal` instead of `127.0.0.1` to reach the host:
  536. ```bash
  537. docker run ... -e KINDLY_CHROME_PROXY="socks5://host.docker.internal:1080" ...
  538. ```
  539. This only affects Chromium-based `page_content` extraction. Search API calls (Serper, Tavily, SearXNG) use `httpx` and respect standard `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` environment variables instead.
  540. Note: Chromium's `--proxy-server` does not support embedded credentials (e.g. `socks5://user:pass@host:port` will not work). If your proxy requires authentication, set up a local credential-less proxy forwarder (e.g. SSH tunnel, `gost`, `socat`) and point `KINDLY_CHROME_PROXY` to the local endpoint.
  541. ### Proxy bypass list
  542. Set `KINDLY_CHROME_PROXY_BYPASS` to exclude specific hosts from the proxy. The value is passed directly as Chromium's `--proxy-bypass-list` flag (comma-separated). Syntax:
  543. - Exact host: `localhost`, `127.0.0.1`
  544. - Wildcard suffix: `*.example.com`, `.local`
  545. - IPv6: `[::1]`
  546. ```bash
  547. export KINDLY_CHROME_PROXY_BYPASS="localhost,127.0.0.1,*.internal"
  548. ```
  549. When unset, Chromium uses its default bypass list (which includes `localhost` and `127.0.0.1`).
  550. ## Remote / Docker deployment (separate machine)
  551. Whether you can run the MCP server on a different PC depends on your MCP client:
  552. - **Stdio / command-based clients** (config uses `command` + `args` to spawn the server): the server must run on the same machine (or at least somewhere the client can run the command). You can still use Docker, but locally (the client launches `docker run ...`).
  553. - **HTTP-capable clients** (can connect to a server URL): you can run Kindly remotely in Docker using **Streamable HTTP**.
  554. ### Prebuilt image (GHCR)
  555. Pull the image instead of building it. It is published for Intel/AMD
  556. (`linux/amd64`) and ARM (`linux/arm64`) — so it runs on ordinary servers and PCs,
  557. on an Apple Silicon Mac, and on ARM cloud instances:
  558. ```bash
  559. # Newest build of the default branch:
  560. docker pull ghcr.io/shelpuk-ai-technology-consulting/kindly-web-search-mcp-server:latest
  561. # Or one build that never changes, using its digest from the package page:
  562. docker pull ghcr.io/shelpuk-ai-technology-consulting/kindly-web-search-mcp-server@sha256:<digest>
  563. ```
  564. > **If `docker pull` says `denied` or `unauthorized`**, the package is still
  565. > private. GitHub creates a new container package as private even under a public
  566. > repository — a package inherits the repository's permissions but not its
  567. > visibility, and there is no API for it. A maintainer has to open the package's
  568. > **Package settings** once and set visibility to Public.
  569. Two tags track the newest build of the default branch and therefore **move**:
  570. `latest`, and the package version the image contains (the `version` in
  571. `pyproject.toml`). Pin the `@sha256:` digest when you need a build that never
  572. changes.
  573. Run it the same way as a locally built image — just use the full name:
  574. ```bash
  575. docker run --rm -p 8000:8000 \
  576. -e SERPER_API_KEY="..." \
  577. -e GITHUB_TOKEN="..." \
  578. ghcr.io/shelpuk-ai-technology-consulting/kindly-web-search-mcp-server \
  579. --http --host 0.0.0.0 --port 8000
  580. ```
  581. See the section below for the other environment variables and the allowlist
  582. caveats — they apply identically to the prebuilt image.
  583. ### Docker (Streamable HTTP)
  584. Or build the image yourself:
  585. ```bash
  586. docker build -t kindly-web-search-mcp-server .
  587. ```
  588. Run the server (port `8000`):
  589. ```bash
  590. docker run --rm -p 8000:8000 \
  591. -e SERPER_API_KEY="..." \
  592. -e GITHUB_TOKEN="..." \
  593. -e KINDLY_CHROME_PROXY="socks5://host.docker.internal:1080" \
  594. kindly-web-search-mcp-server \
  595. --http --host 0.0.0.0 --port 8000
  596. ```
  597. - Or (Tavily):
  598. ```bash
  599. docker run --rm -p 8000:8000 \
  600. -e TAVILY_API_KEY="..." \
  601. -e GITHUB_TOKEN="..." \
  602. -e KINDLY_CHROME_PROXY="socks5://host.docker.internal:1080" \
  603. kindly-web-search-mcp-server \
  604. --http --host 0.0.0.0 --port 8000
  605. ```
  606. - MCP endpoint: `http://<server-host>:8000/mcp`
  607. - Make sure at least one of `SERPER_API_KEY` / `SERPBASE_API_KEY` / `TAVILY_API_KEY` / `SEARXNG_BASE_URL` / `SOFYA_API_KEY` / `YDC_API_KEY` / `SERPLY_API_KEY` / `APIFARE_TOKEN` is set.
  608. - `page_content` extraction runs on the server machine/container (this Docker image includes Chromium).
  609. - Remote HTTP is typically **unauthenticated** and **unencrypted** by default; don’t expose this port publicly. Use VPN/firewall rules or a reverse proxy with TLS + auth.
  610. - Don’t bake API keys into the image; pass them via env vars at runtime.
  611. ### Host and origin allowlists (`421` and `403` errors)
  612. The HTTP transports enforce DNS rebinding protection. Out of the box only loopback is
  613. accepted — `127.0.0.1`, `localhost` and `[::1]` — which covers `docker run -p 8000:8000`
  614. reached as `http://localhost:8000/mcp`, but not much else. Reach the server under any
  615. other name (a Compose service name, a LAN address, a reverse-proxy hostname) and you get:
  616. - `421 Invalid Host header` — the `Host` header isn’t in the allowlist.
  617. - `403 Invalid Origin header` — a browser-based client sent an `Origin` that isn’t.
  618. Widen the allowlist with two comma-separated variables:
  619. | Variable | Matches against | Example |
  620. |---|---|---|
  621. | `FASTMCP_ALLOWED_HOSTS` | the `Host` header | `kindly-web-search-mcp:*,localhost:*,127.0.0.1:*` |
  622. | `FASTMCP_ALLOWED_ORIGINS` | the `Origin` header (browser clients) | `http://localhost:*,https://app.example` |
  623. Syntax notes:
  624. - An entry is either an **exact** value or a `name:*` **port wildcard**. A bare `*` matches
  625. nothing — `FASTMCP_ALLOWED_HOSTS=*` rejects every request.
  626. - `kindly-web-search-mcp:*` matches `kindly-web-search-mcp:8000` but **not** a portless
  627. `Host: kindly-web-search-mcp`. List both if your client may omit the port.
  628. - Setting a variable **replaces** the loopback defaults for that header rather than adding
  629. to them. Keep `localhost:*` and `127.0.0.1:*` in the list if you still want local access.
  630. - The two default independently. Setting only `FASTMCP_ALLOWED_HOSTS` keeps the loopback
  631. origins, so browser clients on `http://localhost:<port>` keep working.
  632. - CORS is derived from `FASTMCP_ALLOWED_ORIGINS`, so an origin that passes preflight is
  633. always one the server will also accept on the real request.
  634. Neither variable is a way to turn the protection off, and that is deliberate: this server
  635. is unauthenticated, and `get_content` will fetch any URL it is given from wherever it runs.
  636. An open allowlist lets any web page you happen to visit drive it against your own network
  637. and read the response. List the hosts you actually use.
  638. ### Docker-compose
  639. Add a subsection to `services:` in your `docker-compose.yml`. Setup variables as described above.
  640. ```yaml
  641. kindly-web-search-mcp:
  642. build:
  643. context: https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server.git#main
  644. container_name: kindly-web-search-mcp
  645. restart: unless-stopped
  646. ports:
  647. - "8000:8000"
  648. environment:
  649. - SEARXNG_BASE_URL=...
  650. - GITHUB_TOKEN=${KINDLY_GITHUB_TOKEN:-}
  651. - FASTMCP_HOST=0.0.0.0
  652. - FASTMCP_PORT=8000
  653. - FASTMCP_TRANSPORT=http
  654. # Other containers reach this one by its service name, which is not loopback.
  655. # Without this you get `421 Invalid Host header`. See the section above.
  656. - FASTMCP_ALLOWED_HOSTS=kindly-web-search-mcp:*,localhost:*,127.0.0.1:*
  657. ```
  658. `FASTMCP_TRANSPORT` can be `streamable-http` (or simply `http`) for Streamable HTTP, `sse` for SSE.
  659. It is read by every entry point, including `kindly-web-search-mcp-server start-mcp-server`.
  660. An unrecognised value logs a warning and falls back to stdio.
  661. Run with:
  662. ```bash
  663. docker compose up -d
  664. ```
  665. Container will be built at the first run. To rebuild it, append `--build` to the command above.
  666. To use the prebuilt image instead of building, replace the `build:` and `context:` lines with:
  667. ```yaml
  668. image: ghcr.io/shelpuk-ai-technology-consulting/kindly-web-search-mcp-server:latest
  669. ```
  670. > **Warning:** `ports: - "8000:8000"` publishes the server on **all** host interfaces. As with
  671. > `docker run` above, remote HTTP here is **unauthenticated** and **unencrypted** — don’t expose
  672. > this port publicly. Bind it to loopback (`"127.0.0.1:8000:8000"`), keep it on an internal
  673. > Compose network, or put a reverse proxy with TLS + auth in front.
  674. ## Troubleshooting
  675. - “No Chromium-based browser executable found”: install Chrome/Chromium/Edge and set `KINDLY_BROWSER_EXECUTABLE_PATH` if needed.
  676. - “Failed to connect to browser”: increase retries/timeouts:
  677. - `KINDLY_NODRIVER_RETRY_ATTEMPTS=5`
  678. - `KINDLY_NODRIVER_DEVTOOLS_READY_TIMEOUT_SECONDS=20`
  679. - Ensure proxy/VPN env vars don’t hijack localhost (set `NO_PROXY=localhost,127.0.0.1` if you use `HTTP_PROXY`/`HTTPS_PROXY`)
  680. - `KINDLY_HTML_TOTAL_TIMEOUT_SECONDS=45`
  681. - `page_content` shows `_Failed to retrieve page content: TimeoutError_` (can happen on any OS, especially **Windows**): the MCP tool time budget was exceeded (often due to slower headless browser cold starts).
  682. - How to spot it: one or more results include `_Failed to retrieve page content: TimeoutError_` in `page_content` (or `get_content(url)` returns that message).
  683. - Fix: increase `KINDLY_TOOL_TOTAL_TIMEOUT_SECONDS` (and, if needed, raise the cap `KINDLY_TOOL_TOTAL_TIMEOUT_MAX_SECONDS`).
  684. - Env vars:
  685. - `KINDLY_TOOL_TOTAL_TIMEOUT_SECONDS`: total time budget per `web_search` / `get_content` call (search + extraction). Default: `120`.
  686. - `KINDLY_TOOL_TOTAL_TIMEOUT_MAX_SECONDS`: caps the above value (safety). Default: `600`.
  687. - `KINDLY_WEB_SEARCH_MAX_CONCURRENCY`: max parallel content fetches. Default: `3` (when unset or invalid); clamped 1..5.
  688. - Recommended starting point (PowerShell):
  689. - `$env:KINDLY_TOOL_TOTAL_TIMEOUT_SECONDS="180"`
  690. - `$env:KINDLY_TOOL_TOTAL_TIMEOUT_MAX_SECONDS="600"`
  691. - Optional (reduces parallel browser work): `$env:KINDLY_WEB_SEARCH_MAX_CONCURRENCY="1"`
  692. - Browser reuse is on by default for universal HTML loading. Note: pooled Chromium shares state across requests (cookies, local storage, cache, and user-agent from the first request handled by each slot).
  693. - `KINDLY_NODRIVER_REUSE_BROWSER=0` disables reuse (fresh Chromium per request).
  694. - `KINDLY_NODRIVER_BROWSER_POOL_SIZE=2` controls how many Chromium instances are kept warm.
  695. - `KINDLY_NODRIVER_ACQUIRE_TIMEOUT_SECONDS=30` controls how long to wait for a pooled slot before falling back to per-request Chromium.
  696. - `KINDLY_NODRIVER_BROWSER_IDLE_TIMEOUT_SECONDS=600` closes a pooled Chromium once it has sat unused that many seconds, so an idle server stops holding a browser's memory. The next request launches a fresh one, from a fresh profile, and pays a cold start (diagnostics emit `pool.slot_idle_closed`). With a pool larger than one, the most recently used running browser is handed out first, so light traffic keeps one browser warm and lets the rest close. Unset, the default, never closes a browser for being idle, and slots are handed out in turn as before.
  697. - Optional: `KINDLY_NODRIVER_PORT_RANGE=45000-45100` restricts remote debugging ports.
  698. - Pooled slots are health-checked before use and auto-restarted if the DevTools endpoint is stale (diagnostics emit `pool.slot_probe` and `pool.slot_restart`).
  699. - If pool acquisition times out or fails, the server falls back to per-request Chromium and emits a `pool.acquire_timeout`/`pool.slot_error` diagnostic when diagnostics are enabled.
  700. - A request that times out or is cancelled has its browser killed mid-page, so that slot is recycled rather than reused: the request still fails with its own timeout, and the *next* request gets a freshly launched Chromium (diagnostics emit `pool.slot_recycled`). Repeated `pool.slot_recycled` records mean reuse is paying a cold start per request — raise `KINDLY_TOOL_TOTAL_TIMEOUT_SECONDS` or `KINDLY_HTML_TOTAL_TIMEOUT_SECONDS` rather than the pool settings.
  701. - Need deeper debugging? Enable diagnostics:
  702. - Set `KINDLY_DIAGNOSTICS=1` to emit JSON-line diagnostics to stderr and include `diagnostics` in tool responses.
  703. - `get_content` returns top-level `diagnostics`; `web_search` attaches `diagnostics` per result.
  704. - `OSError: [Errno 39] Directory not empty: '/tmp/kindly-nodriver-.../Default'`: update to the latest server revision (uv may cache tool envs; `uv cache clean` can help).
  705. - “web_search fails: no provider key”: set `SERPER_API_KEY`, `SERPBASE_API_KEY`, `TAVILY_API_KEY`, `SEARXNG_BASE_URL`, `SOFYA_API_KEY`, `YDC_API_KEY`, `SERPLY_API_KEY`, or `APIFARE_TOKEN`.
  706. ## Security
  707. - Don’t commit API keys.
  708. - Prefer env-var expansion (Codex `env_vars`, Cursor `${env:...}`, Gemini `$VAR`, Claude Code `${VAR}`) instead of hardcoding secrets.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.