Skip to main content
Glama
telly6

searchpin

English | 简体中文

Searchpin

PyPI version Python License Docker

Self-hosted web search for AI agents — zero API keys, zero cost. In 2026, the center of gravity in AI development is shifting from "chatting" to "autonomous task execution" — locally deployed, long-running agents are becoming the norm. When an agent runs 24/7, every web search must not be interrupted by API quotas or billing. Searchpin was designed for this from day one: zero external dependencies, zero usage limits. Agents can search, fetch, and verify without restriction, and developers never worry about cost.

Why Searchpin

🇨🇳 Optimized for Chinese Network Environments

Defaults to Baidu, Sogou, Bing CN, and Bing Intl — four search engines queried in parallel. Works natively within China's network, no proxy or VPN needed. Most overseas alternatives rely on Google, DuckDuckGo, or Brave, which are largely inaccessible inside China.

🧠 Semantic Re-ranking — a Differentiator Few Offer

Results from all four engines are not simply concatenated. They are merged and re-ranked by an embedding model based on semantic similarity to the query. What your AI receives is a curated list of high-quality results, not a pile of noisy links. Among free MCP search servers, very few offer this capability.

💰 Completely Free, Zero Barrier

No account registration, no API key application, no usage limits. No dependency on any commercial API — no risk of sudden paywalls or quota restrictions. The entire pipeline runs on your own machine.

🔍 Built for Modern Websites

Built-in SSR content extraction can parse pages rendered by Next.js, Nuxt, and similar frameworks, and extract JSON-LD structured data and microdata. Plain HTML scraping gets nothing from these sites.

🛡️ Pollution Detection + Cross-Verification

Automatically detects and flags results unrelated to your query. Four independent search engines provide cross-verifiable results, enabling your LLM to corroborate information across sources for more credible answers.

⚡ Deliberate Engineering Trade-offs

Every design decision was made with real-world usage in mind:

  • Token-conscious — Search results return only titles, URLs, and snippets. Structured extraction data is compact and truncated. Your LLM decides which pages are worth fetching in full, without wasting context window.

  • Fast response — Four engines queried asynchronously in parallel. Total time depends on the slowest engine, not the sum of all four. A typical search completes in 1–2 seconds.

  • Memory-friendly — The embedding model (~118MB) is downloaded once through hf-mirror.com (HuggingFace mirror for China), then reused from local cache.

Related MCP server: Argus

Quick Start

pip install searchpin && searchpin-setup

On first run, the embedding model (~118MB) is downloaded once via hf-mirror.com (HuggingFace mirror for China). That is the only one-time setup.

Configuration

Claude Desktop / Cursor / any MCP client

Add to your mcpServers config:

{
  "mcpServers": {
    "Searchpin": {
      "command": "searchpin-server",
      "args": []
    }
  }
}

VS Code

Install in VS Code Install in VS Code Insiders

Or manually, add to .vscode/mcp.json:

{
  "servers": {
    "Searchpin": {
      "command": "searchpin-server",
      "args": []
    }
  }
}

Docker

docker run -i --rm ghcr.io/telly6/searchpin:latest

Python API

from searchpin import SearchEngine

engine = SearchEngine()
results = engine.search("Python 3.13 新特性")
page = engine.fetch("https://docs.python.org/3/whatsnew/3.13.html")
engine.close()

Available Tools

2 tools
web_fetchA

Fetch a URL and return clean, extracted text content (boilerplate, ads, and nav removed). Use to read articles, documentation pages, or API responses in full. For broad queries, use web_search first, then fetch specific URLs from its results. After fetching, look for technical terms, names, or references you can use as keywords for a better follow-up search.

⚠️ FAILURE IS NORMAL — DO NOT GIVE UP AFTER 1-2 FAILED FETCHES:

  • If a fetch returns empty body, 403, or obvious JS-template garbage, try the NEXT URL from the search results immediately. Each retry costs only ~0.5s.

  • Common failure causes: JS-rendered SPA shells (stock pages, forums), Chinese paywalls/captchas (wenku.baidu.com, zhihu.com), government site timeouts.

  • Rule of thumb: try at least 3 URLs from 3 different domains before concluding the content is unreachable. Skipping this wastes the search you already paid for.

  • When retrying, pick a URL from a DIFFERENT domain — same-domain failures often share the same root cause (e.g., all pages behind the same Cloudflare/WAF).

RETRY SILENTLY: When a fetch fails, retry with the next URL immediately as another tool call. Do NOT narrate each failure to the user ('this one failed, trying another…'). Only mention failures in your final reply if ALL attempts were exhausted.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to fetch

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It discloses failure modes (JS-rendered SPAs, paywalls, timeouts), latency (~0.5s per retry), and the expected retry behavior. It also explains the cleanup of boilerplate/ads/nav, so the agent knows what to expect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: purpose first, then usage guidance, then a detailed failure handling section with bullet points. Each sentence adds value, and the length is justified by the complexity of the tool's failure behavior. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter and no output schema, the description covers everything needed: input, output, failure modes, retry strategy, and integration with web_search. It is self-contained and leaves no ambiguity for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has one parameter 'url' with description 'The URL to fetch'. The tool description adds contextual usage (e.g., URLs come from search results) but no new format constraints or additional semantics. Since schema coverage is 100%, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Fetch'), resource ('URL'), and output ('clean, extracted text content'). It distinguishes from sibling tool 'web_search' by advising to use search first then fetch specific URLs. The purpose is precise and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use web_search first and then fetch, and provides a detailed retry strategy: try at least 3 URLs from different domains, retry silently, and common failure causes. This is comprehensive guidance beyond a simple description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.8
    • First observedweb_fetch
    • First observedweb_search

TDQS

A4.7/5.0

Scored across 2 tools

Disambiguation5/5

web_search and web_fetch have clearly distinct purposes: one handles query-based web search, the other fetches and extracts content from specific URLs. No overlap or ambiguity.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern in snake_case: web_search, web_fetch. The naming is predictable and clear.

Tool Count4/5

With only 2 tools, the server is minimal but appropriate for its focused search-and-fetch domain. The count is not excessive, though a few more specialized search utilities could be added.

Completeness4/5

The server covers the essential search and fetch operations. The extensive instructions compensate for missing advanced features, but minor gaps like image search exist.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    An advanced web browsing server enabling headless browser interactions via a secure API, providing features like navigation, content extraction, element interaction, and screenshot capture.
    6
    27
    MIT
  • A
    license
    B
    quality
    A
    maintenance
    One endpoint, five search providers. Search broker for AI agents with automatic fallback, RRF ranking, and budget enforcement. The LiteLLM of web search.
    13
    5
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Web search for AI agents across 6 engines (Serper, Brave, Exa, Tavily, Firecrawl, Perplexity) through one search tool. Routes each query to the cheapest engine that clears a quality bar and caches repeats. Hosted, streamable-HTTP, BYOK supported.
    1
    1
    MIT
  • A
    license
    A
    quality
    F
    maintenance
    Free multi-source web search server for AI agents, with confidence scoring and token optimization.
    3
    56 npm
    Apache 2.0