SkillAgentSearch skills...

agentSearcher

Self-hosted MCP server and Tavily-compatible API for AI agents: web search, extract, crawl and map in one lightweight CPU-only Python process. JS pages via headless Chromium, PDF, no API keys.

Install / Use

claude mcp add peakQuick -- npx -y github:peakQuick/agentSearcher

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

81/100

Supported Platforms

Claude Code
Claude Desktop

Our assessment of agentSearcher

agentSearcher scores 81/100 on our quality scale, 716th of 947 AI & Machine Learning skills we index.

Its MCP Server is 8.4 KB long, well organised into 15 sections with 11 code examples: a thorough specification that gives an agent plenty to work with.

It has 3 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
29/30
Structure
20/20
Description
15/15
Adoption
3/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 20 days ago, so agentSearcher is actively maintained.
  • It is released under AGPL-3.0, a copyleft license: you can use it, but modified versions you distribute must carry the same license.
  • Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-15. Automated pattern scan on 2026-11-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

agentSearcher compared with similar skills

All 4 of these similar skills score higher than agentSearcher; compare them before choosing.

SkillScoreStarsUpdatedFormat
agentSearcher (this skill)by peakQuick81320d agoMCP Server
claude-memby thedotmack100117.6ktodayCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
Understand-Anythingby Egonex-AI10092.8k1d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md

Frequently asked questions

How do I install agentSearcher?
Run claude mcp add peakQuick -- npx -y github:peakQuick/agentSearcher. The install tabs above show the steps for each supported agent.
Which AI agents does agentSearcher work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is agentSearcher safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is AGPL-3.0-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is agentSearcher still maintained?
The repository was last updated 20 days ago, so agentSearcher is actively maintained.
<div align="center">

agentsearcher

Lightweight local web retrieval for AI agents: search, extract, crawl and map in one CPU-only process. No cloud keys.

Python License: AGPL-3.0 Tavily-compatible MCP

</div>

An agent that works with the web needs to find pages, read them (including JavaScript pages and PDFs) and sometimes walk a whole site. agentsearcher does all of it in one Python process and returns only the passages that matter, sized for a small context window. It is available as an MCP server, an HTTP API (Tavily-compatible) and a CLI, with a dashboard in the browser.

Contents

Why

Self-hosted web retrieval usually means assembling several services: a metasearch engine such as SearXNG for search, a crawler such as Crawl4AI for page content, or a self-hosted Firecrawl, which runs as an API plus a browser service, Redis, RabbitMQ and Postgres. agentsearcher is one process instead:

  • Light. ~75 MB idle; ~380 MB while ranking with the model; Chromium only starts for pages that need it. The model and the browser are unloaded after 2 minutes idle. Measured on a laptop i7-7500U with 7.5 GB RAM, no GPU (details).
  • Search and reading together. One query fetches, renders, cleans and ranks the result pages, so the agent gets relevant passages instead of snippets or whole pages.
  • Made for agents. Responses fit a small context window; reprints and near-duplicates are dropped; results the search engines agree on rank higher than SEO pages one engine pushes up.
  • Easy to run. pipx install or docker compose up. Nothing to configure to get started.

Features

  • MCP server (stdio, or streamable HTTP at /mcp on the API port) with the tools web_search, web_extract, web_crawl and web_map. An env flag renames them to tavily_*.
  • JavaScript pages: when a plain fetch isn't enough, the page is rendered in headless Chromium.
  • PDF: the text layer is read. No OCR.
  • sitemap.xml, robots.txt and llms.txt are used by map/crawl, and .md versions of pages by extract/crawl. Sites without these files work too.
  • Reprints and near-duplicate chunks are dropped (dedup), and results can be capped per domain (max_per_domain).
  • SSRF protection: localhost and private networks are blocked by default.
  • Response size is capped to fit a small context window. The model and the browser are unloaded after a period of inactivity.
  • Pages and search results are cached for 15 minutes; optional block/lower/raise rules per domain.
  • Dashboard at /: request and page counters, CPU and memory (with the browser), recent requests, and a playground for search, extract, crawl and map.
  • Drop-in for Tavily clients: /search, /extract, /crawl, /map, /usage respond in the Tavily API format, so existing clients only change the base URL. Covered by tests with the official tavily-python client.

How it works

query ─► search engines (ddgs: duckduckgo, yahoo, yandex, brave, mojeek, bing; optional SearXNG)
      ─► fetch pages with curl_cffi (Chrome TLS fingerprint)
           └─ empty page / SPA / anti-bot / text doesn't match snippet ─► patchright Chromium
      ─► trafilatura → markdown (PDF → text layer) ─► ~600-char chunks
      ─► BM25 ─► multilingual cross-encoder (ONNX int8, CPU)
      ─► dedup ─► only the best chunks of each page go into the response

Details: docs/how-it-works.md.

Installation

Docker (Chromium and the model are inside the image):

git clone https://github.com/peakQuick/agentSearcher.git && cd agentSearcher
docker compose up -d --build        # API and MCP at http://127.0.0.1:8484, MCP at /mcp

Settings go under environment: in compose.yaml. On macOS and Windows, Docker Desktop runs a VM, which costs extra RAM; there, the pipx install below is lighter.

pipx (no venv to manage; pipx is in most package managers: apt install pipx, brew install pipx, pacman -S python-pipx):

pipx install git+https://github.com/peakQuick/agentSearcher
agentsearcher setup                 # one time: Chromium (~/.cache/ms-playwright) and the ~120 MB reranker (~/.cache/huggingface)
agentsearcher serve

Update with pipx upgrade agentsearcher. On a bare Linux server, agentsearcher setup --with-deps also installs Chromium's system libraries (needs root).

From source (development):

git clone https://github.com/peakQuick/agentSearcher.git && cd agentSearcher
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/agentsearcher setup

Below, agentsearcher means the installed command (.venv/bin/agentsearcher for a source install).

Quick start

CLI

agentsearcher search "what's new in python 3.14"
agentsearcher extract https://react.dev/learn -q "useState"
agentsearcher map https://docs.python.org/3/

HTTP API

agentsearcher serve                                    # dashboard: open http://127.0.0.1:8484/
curl -s localhost:8484/search -H 'Content-Type: application/json' \
  -d '{"query": "python asyncio tutorial", "max_results": 3}'

With tavily-python:

from tavily import TavilyClient

client = TavilyClient(api_key="local", api_base_url="http://127.0.0.1:8484")
print(client.search("python asyncio tutorial", max_results=3)["results"][0]["url"])

MCP

With serve or Docker running, HTTP clients and web UIs connect to http://127.0.0.1:8484/mcp:

claude mcp add --transport http agentsearcher http://127.0.0.1:8484/mcp

Or let the client start its own server over stdio:

claude mcp add agentsearcher -- agentsearcher mcp

Other clients: docs/mcp.md.

Configuration

The defaults work as is. Settings are environment variables with the AGENTSEARCHER_ prefix:

AGENTSEARCHER_API_KEYS=change-me agentsearcher serve     # pipx / source

With Docker, put them under environment: in compose.yaml; for MCP over stdio, in the client's env block. GET /stats shows the values in effect (secrets hidden).

The ones people usually change: API_KEYS (before opening the server to a network), PROXY_URL (search engines block your IP), LLM_BASE_URL (answers with include_answer), MAX_REQUESTS / MAX_RENDERS (a machine with little RAM). All variables and ready-made recipes: docs/configuration.md.

Search depth

| mode | what it does | warm latency* | |---|---|---| | ultra-fast | search engine snippets only, no pages fetched | ~1 s | | fast | pages without the browser, BM25 ranking | 3–4 s | | basic | + browser for JS and anti-bot pages, + cross-encoder | 6–9 s | | advanced | + more candidates, favor_recall, stricter about "empty" pages | 7–10 s |

* i7-7500U, 5 results. The first request takes longer: ~1.5 s to load the model and ~1 s to start the browser.

Documentation

| doc | what's inside | |---|---| | CLI | commands, flags and how to read the log | | HTTP API | endpoints, parameters, responses and errors | | MCP | tools and client setup | | Configuration | environment variables | | How it works | pipeline, browser, ranking, crawling, PDF, dedup, memory | | Security | SSRF protection | | Limitations | known limitations and possible problems |

Development

.venv/bin/ruff check .
.venv/bin/python -m pytest -m "not live"   # offline: local fixture sites (SPA, challenge, PDF, sitemap...), tavily-python contract
.venv/bin/python -m pytest -m live         # needs internet: tavily-python search at every search_depth

License

Copyright (C) 2026 peakQuick

GNU Affero General Public License v3.0. If you modify this project and let others use it over a network, you must make the source code of your modified version available to those users.

Related Skills

View on GitHub
GitHub Stars3
CategoryAI
Updated20d ago
Forks0

Languages

Python

Trust signals

92/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 low