Metadata-Version: 2.4
Name: grounder-mcp
Version: 0.4.1
Summary: Live web search, page fetch, and a token-capped cited evidence pack as MCP tools for local and cloud LLMs.
License: MIT
Project-URL: Homepage, https://grounder.dev
Project-URL: Documentation, https://grounder.dev/docs
Project-URL: Repository, https://github.com/rozetyp/grounder-mcp
Keywords: mcp,web-search,fetch,deep-search,rag,grounding,llm,ollama,lm-studio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.2
Requires-Dist: httpx>=0.27
Dynamic: license-file

# Grounder MCP

Live web grounding for local and cloud LLMs, as four MCP tools. Every model is frozen at its
training cutoff; Grounder gives yours the current web - ranked results, real page content, and a
cited evidence pack sized to your context window.

A thin stdio client for the hosted service at https://grounder.dev - no browser, no scraper,
nothing heavy runs locally. It runs with **no signup** on a shared demo key; add your own free key
(1,500 pages/month, no card) at grounder.dev for real use.

## Install

```bash
uvx grounder-mcp          # or: pip install grounder-mcp
```

## Configure

Claude Desktop, Cursor, LM Studio, Continue.dev, or any MCP client. The key is **optional** - omit
it to try Grounder on the shared demo key, or add your own free key from grounder.dev:

```json
{
  "mcpServers": {
    "grounder": {
      "command": "uvx",
      "args": ["grounder-mcp"],
      "env": { "GROUNDER_API_KEY": "gnd_live_your_key" }
    }
  }
}
```

## The four tools

| Tool | What it does |
|---|---|
| `web_search` | Google organic results plus people-also-ask, related searches, and the knowledge graph. The top snippet often already holds the answer. |
| `fetch` | One page as clean markdown, capped to your token budget, plus the final URL after redirects. |
| `deep_search` | One search, read across the pages it surfaces, ranked into a token-capped, cited evidence pack. Optional grounded answer. |
| `research` | Investigates an open question with no ready-made answer: it plans, reads primary sources, notices what is missing, goes back for it, and reasons to a grounded conclusion. |

## Why use it

- **It fits a small context window.** Results come back token-capped, so they slot into an 8-32k
  local model instead of overflowing it. A few raw pages can be 20,000+ tokens (we measured 22,759
  for one query) - enough to make a small model return nothing. You get the relevant passages, not
  whole pages.
- **The live page, not a cached copy.** `fetch` reads the actual current page; any caching is short,
  timestamped, and force-refreshable.
- **Flat monthly price, billed in pages.** You only pay for pages actually delivered. No per-call metering.
- **No query content stored.** Ever.

## Pricing

Free: 1,500 pages/month, no card. Starter $9/mo, Pro $19/mo. Full table at https://grounder.dev/pricing.

<!-- mcp-name: io.github.rozetyp/grounder -->
