convez.ai
MCP Server
Ketlark

hugin-mcp

Ketlark/hugin-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

🪶 100% local, 100% free MCP server for web search & reading — no API keys needed

Instalação

$npx convez-ai Ketlark/hugin-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.


Two tools become four. That's all your agent needs.

web_search("rust async tutorial")          → 10 results from 70+ engines
web_read("https://github.com/...")          → clean markdown, zero noise
web_search_read("rust async tutorial")      → search + read top 3 in one call
web_screenshot("https://example.com")       → PNG screenshot of any page

Hugin runs a local SearXNG metasearch engine and 14 specialized page readers. Named after Odin's raven who scouted the world each morning and came back with answers.


Install

Step 1 — Docker

SearXNG runs in Docker and aggregates 70+ search engines (Google, Bing, DuckDuckGo, Brave, Startpage…). Without it, Hugin falls back to Bing — works, but limited.

# Make sure Docker is running, then:
docker compose up -d

No Docker? Install Docker Desktop first.

Step 2 — MCP client

Pick your client below.

claude mcp add hugin-mcp -- npx -y @ketlark/hugin-mcp@latest

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "hugin-mcp": {
      "command": "npx",
      "args": ["-y", "@ketlark/hugin-mcp@latest"]
    }
  }
}

.cursor/mcp.json at project root:

{
  "mcpServers": {
    "hugin-mcp": {
      "command": "npx",
      "args": ["-y", "@ketlark/hugin-mcp@latest"]
    }
  }
}

Same pattern — point to npx -y @ketlark/hugin-mcp@latest:

{
  "mcpServers": {
    "hugin-mcp": {
      "command": "npx",
      "args": ["-y", "@ketlark/hugin-mcp@latest"]
    }
  }
}

Step 3 — Verify (optional)

npx @ketlark/hugin-mcp setup

This checks Docker, SearXNG, Chrome, and prints a status report.


Tools

web_search

{
  "query": "rust async await tutorial",
  "count": 10,
  "engine": "auto",
  "categories": "general",
  "language": "en",
  "time_range": "month",
  "domains": ["github.com", "stackoverflow.com"],
  "filetype": "pdf"
}
ParameterDefaultDescription
queryrequiredSearch query. Supports site:, "exact", -exclude
count10Max results (1–20)
engine"auto""auto", "searxng", or "bing"
categories—general, news, images, videos, it, science, music, files, social media
languageautoen, fr, de, es, ja, zh, etc.
time_range—day, month, year
pageno1Page number
domains—Restrict to specific domains, e.g. ["github.com"]
filetype—Restrict to file type, e.g. "pdf", "doc"

Results are cached for 24 hours.

web_read

Single URL:

{ "url": "https://github.com/microsoft/typescript/issues/1" }

Batch — read multiple URLs in parallel:

{
  "urls": [
    "https://github.com/owner/repo",
    "https://www.reddit.com/r/programming",
    "https://en.wikipedia.org/wiki/Rust_(programming_language)"
  ]
}
ParameterDefaultDescription
url—Single URL to read
urls—Multiple URLs for batch parallel reads
format"markdown""markdown" or "text"
llmfalseUse ReaderLM-v2 for higher quality (slower, requires LM Studio)
with_links_summaryfalseExtract link summary
with_images_summaryfalseExtract image summary
max_length—Truncate content to N characters

Content is cached for 24 hours.

web_search_read

Search + read in one call. Eliminates the need for separate search → read → read round trips.

{
  "query": "rust async await tutorial",
  "count": 10,
  "read_count": 3,
  "max_length": 5000
}
ParameterDefaultDescription
queryrequiredSearch query
count10Max search results (1–20)
read_count3Number of top results to auto-read (1–5)
engine"auto""auto", "searxng", or "bing"
categories—Same as web_search
languageautoSame as web_search
time_range—Same as web_search
domains—Same as web_search
filetype—Same as web_search
format"markdown""markdown" or "text"
max_length—Max content chars per page read

web_screenshot

Capture a screenshot of any web page. Returns a PNG or JPEG image.

{
  "url": "https://github.com",
  "width": 1280,
  "height": 800,
  "full_page": false,
  "format": "png"
}
ParameterDefaultDescription
urlrequiredURL to screenshot
width1280Viewport width in pixels
height800Viewport height in pixels
full_pagefalseCapture the full scrollable page
format"png""png" or "jpeg"

Requires Chrome/Chromium installed.


Why Hugin

14 specialized readers. Hugin detects the site you're reading and uses a dedicated API instead of generic HTML scraping. GitHub issues → REST API. YouTube → transcript API. Wikipedia → MediaWiki. Cleaner output, faster responses, fewer rate limits.

SiteMethodAuth?
GitHub (issues, PRs, repos, files)REST APINo (60 req/h)
Reddit (posts, comments, subreddits)JSON APINo
YouTube (transcripts with timestamps)Innertube APINo
HackerNews (stories, comments)Firebase APINo
StackExchange (300+ Q&A sites)Public APINo
WikipediaMediaWiki APINo
ArXiv (papers, abstract)HTML scrapingNo
MDN Web Docsindex.json APINo
npm packagesRegistry APINo
Docker Hub (images, tags)v2 APINo
PDF filespdf-parse—
Any other pageReadability + Turndown + Puppeteer fallback—

SQLite cache. Every search result and page read gets cached for 24 hours. Your agent won't re-fetch the same page twice in a session.

Zero config. Chrome auto-detection across macOS, Linux, Windows (Chrome, Chromium, Brave, Edge). No browser found? Puppeteer features turn off — everything else works.

Graceful fallback chain. SearXNG down? Bing takes over. Readability fails? Puppeteer renders the page. Puppeteer blocked? ReaderLM-v2 can pick it up (if you have LM Studio running).


vs Others

HuginTavilyExaJinaBraveFirecrawl
Cost$0FreemiumPaidFreemium$5/moFreemium
100% local✅❌❌❌❌❌
No API key✅❌❌❌❌❌
Web search✅ 70+ engines✅✅ neural✅✅✅
Page reading✅ 14 handlers✅✅✅❌✅
Search + Read✅ one call✅❌❌❌❌
Screenshots✅❌❌✅❌❌
Batch reads✅❌❌✅❌❌
Cache✅ SQLite❌❌❌❌❌
Domain filters✅❌✅❌✅❌
Data privacyStays on your machineSent to TavilySent to ExaSent to JinaSent to BraveSent to Firecrawl

Every competitor sends your queries or page content to a cloud API. Hugin doesn't.


Configuration

Defaults work out of the box. Override with environment variables or a .env file:

VariableDefaultWhat it does
HUGIN_SEARXNG_URLhttp://localhost:8888SearXNG instance URL
HUGIN_SEARXNG_PORT8888Port for auto-started SearXNG container
HUGIN_LMSTUDIO_URLhttp://localhost:1234LM Studio endpoint (ReaderLM)
HUGIN_READERLM_MODELreaderlm-v2-mlxReaderLM model name
CHROME_PATHauto-detectedChrome/Chromium executable
HUGIN_PUPPETEER_TIMEOUT15000Puppeteer timeout (ms)
HUGIN_CACHE_DIR.cacheSQLite cache directory
HUGIN_CACHE_TTL86400Cache TTL in seconds (24h)
PlatformSearch paths
macOSGoogle Chrome, Chromium, Brave Browser, Microsoft Edge
Linux/usr/bin/google-chrome, /usr/bin/chromium, /usr/bin/brave-browser, /snap/bin/chromium
WindowsC:\Program Files\Google\Chrome\Application\chrome.exe, Brave, Edge

Set CHROME_PATH to override. No browser found = Puppeteer disabled, everything else works.

For complex pages where Readability struggles (heavy JS, nested layouts):

  1. Install LM Studio
  2. Download ReaderLM-v2 (quantized, e.g. readerlm-v2-q8-mlx for Apple Silicon)
  3. Load the model and start the server
  4. Pass "llm": true in web_read

Without ReaderLM, Hugin works fine via Readability + Turndown for the vast majority of pages.


Troubleshooting

SymptomFix
SearXNG unavailable — Bing fallbackRun docker compose up -d or start Docker Desktop
Docker is not installedInstall Docker Desktop
Docker daemon is not runningStart Docker Desktop or run sudo systemctl start docker
No Chrome/Chromium foundSet CHROME_PATH or install Chrome/Chromium
better-sqlite3 build failsInstall python3 + build-essential (Linux) or Xcode CLI tools (macOS)
Cloudflare 403Install Chrome for Puppeteer fallback

Architecture

src/
├── index.js              # MCP entry point
├── setup.js              # Setup command (npx @ketlark/hugin-mcp setup)
├── config.js             # Env vars + platform detection
├── cache.js              # SQLite WAL cache
├── fetcher.js            # HTTP fetch (retry, rate-limit) + Puppeteer
├── html.js               # Readability + Turndown
├── llm.js                # ReaderLM-v2 client
├── screenshot.js         # Puppeteer screenshot → base64
├── format.js             # Response formatters
├── search/
│   ├── searxng.js        # SearXNG client + auto-start + Docker detection
│   └── bing.js           # Bing fallback
└── readers/
    ├── index.js          # URL → reader router
    ├── github.js         # GitHub REST API
    ├── reddit.js         # Reddit JSON API
    ├── youtube.js        # YouTube transcripts
    ├── hackernews.js     # HN Firebase API
    ├── stackexchange.js  # 300+ Q&A sites
    ├── wikipedia.js      # MediaWiki API
    ├── arxiv.js          # ArXiv metadata
    ├── mdn.js            # MDN JSON API
    ├── npm.js            # npm registry
    ├── dockerhub.js      # Docker Hub v2
    └── pdf.js            # PDF text extraction

Reading pipeline:

URL → cache? → specialized reader? → Readability → Turndown → markdown
                     │                     │
                     │                     └→ Puppeteer (SPA/403)
                     └→ ReaderLM (if llm=true)

License

MIT


Hugin depends on SearXNG, Mozilla Readability, Turndown, and Puppeteer.

Ver o original no GitHub

Bom para

Relacionados