🔗 FactAnchor-MCP

Reduce AI Hallucinations by up to ~80% (informal estimate) using Local Context Anchoring.

FactAnchor-MCP is a zero-cost, fully local Model Context Protocol server that grounds your AI assistant (Claude Desktop, Cursor, VS Code, Claude Code) in real, fetched web text — and forces it to answer only from that text.

• 💸 ₹0 Hosting Cost — runs entirely on your machine. No cloud, no paid API keys.

• 🛡️ Strict Guardrails — the LLM must cite sources or say "I cannot find a verified source for this information."

• 🔎 Free Web Fetching — uses DuckDuckGo's free search + page scraping (no Serper/Google keys).

• 🧠 Smart Chunking — BM25 semantic relevance scoring keeps only the most useful paragraphs.

• 💾 Persistent Cache — SQLite disk cache (~/.factanchor/cache.db) survives server restarts.

• ⚡ Zero-config setup — pip install -e . + connect your MCP client. Browser auto-installs on first start.

⭐ If FactAnchor-MCP helps you ship more reliable, hallucination-free AI, please consider starring the repository. It takes one click and helps more developers discover a truly zero-cost way to ground their agents. Thank you! 🙏

🚀 1-Minute Quick Start

Option A — Recommended (cross-platform, no path editing)

git clone https://github.com/Tausifonly001/FactAnchor-MCP.git
cd FactAnchor-MCP
pip install -e .          # installs the `factanchor-mcp` command

Then add this to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "FactAnchor-MCP": {
      "command": "factanchor-mcp"
    }
  }
}

Option B — Simple (use the script path directly)

git clone https://github.com/Tausifonly001/FactAnchor-MCP.git
cd FactAnchor-MCP
pip install -r requirements.txt

Add the absolute path to server.py:

{
  "mcpServers": {
    "FactAnchor-MCP": {
      "command": "python",
      "args": ["/absolute/path/to/FactAnchor-MCP/server.py"]
    }
  }
}

• Windows: "C:\\Users\\you\\FactAnchor-MCP\\server.py"

• macOS / Linux: "/Users/you/FactAnchor-MCP/server.py" or "/home/you/FactAnchor-MCP/server.py"

3. Restart your client

You'll now see the fetch_verified_context tool available. Ask a factual question and watch the assistant ground its answer in live, cited sources.

✅ Zero-config: on first launch, FactAnchor silently installs the Playwright Chromium browser in the background. No crawl4ai-setup or manual browser commands required.

💡 Want uv instead of pip? uv pip install -e . works identically, and the factanchor-mcp command lands on your PATH.

Related MCP server: Grounded Code MCP

🧩 Supported Clients (drop-in configs)

FactAnchor-MCP is a standard MCP server, so it works with any MCP-compatible client. Below are ready-to-paste configs. Every client uses the same two shapes:

• Option A (recommended): "command": "factanchor-mcp" — needs pip install -e . (so the command is on your PATH).

• Option B (path-based): "command": "python" + "args": ["/abs/path/server.py"] — use this if the factanchor-mcp command isn't found.

File: claude_desktop_config.json (Settings → Developer → Edit Config)

{
  "mcpServers": {
    "FactAnchor-MCP": { "command": "factanchor-mcp" }
  }
}

Restart Claude Desktop. Tool appears in the tools list.

File: .opencode.jsonc (project root)

{
  "mcpServers": {
    "FactAnchor-MCP": { "command": "factanchor-mcp" }
  }
}

Verify with /mcp — fetch_verified_context should be listed.

These are Claude-Code-style clients. Use a project .mcp.json:

{
  "mcpServers": {
    "FactAnchor-MCP": { "command": "factanchor-mcp" }
  }
}

Or add it from the CLI (runs the same server):

claude mcp add factanchor -- factanchor-mcp
# Kimi/Qwen/Cline equivalents use the same `mcp add` subcommand

File: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

{
  "mcpServers": {
    "FactAnchor-MCP": { "command": "factanchor-mcp" }
  }
}

Enable it in Settings → MCP and restart Cursor.

File: .vscode/mcp.json (note: VS Code uses a "servers" key)

{
  "servers": {
    "FactAnchor-MCP": {
      "type": "stdio",
      "command": "factanchor-mcp"
    }
  }
}

Open the Command Palette → MCP: List Servers to confirm it's connected.

File: .gemini/settings.json

{
  "mcpServers": {
    "FactAnchor-MCP": { "command": "factanchor-mcp" }
  }
}

Or: gemini mcp add factanchor -- factanchor-mcp

If the factanchor-mcp command isn't on your PATH, use the absolute path to server.py on every client above:

{
  "mcpServers": {
    "FactAnchor-MCP": {
      "command": "python",
      "args": ["/absolute/path/to/FactAnchor-MCP/server.py"]
    }
  }
}

Per-OS path examples:

• Windows: "C:\\Users\\you\\FactAnchor-MCP\\server.py"

• macOS: "/Users/you/FactAnchor-MCP/server.py"

• Linux: "/home/you/FactAnchor-MCP/server.py"

🛠️ How It Works

[Claude Desktop / Cursor / VS Code]
       │ (Asks a factual query)
       ▼
[FactAnchor MCP Server]
       │
       ├──► [Free DuckDuckGo Search] (URL Discovery)
       │
       ├──► [Persistent Cache: ~/.factanchor/cache.db] (Fast Repeat Queries)
       │
       ├──► [Crawl4AI in Isolated Subprocess] (Page Scraping)
       │
       ├──► [BM25 Semantic Chunking] (Smart Paragraph Selection)
       │
       └──► [Strict Guardrail Injection] (Verified Context Block)
              │
              ▼
[Assistant answers ONLY from verified context → ~0% Hallucination]

1. Free Search — fetch_verified_context(query) runs a free DuckDuckGo search to discover URLs. No API keys required.

2. Persistent Caching — results are cached in ~/.factanchor/cache.db (SQLite) for 24 hours, so repeat queries return instantly even after server restarts.

3. Page Scraping — Crawl4AI runs in an isolated subprocess (crawl_worker.py) to scrape discovered URLs into clean, LLM-optimized Markdown (navbars, ads, and footers auto-stripped).

4. Semantic Chunking — BM25 relevance scoring extracts only the paragraphs most relevant to your query, maximizing information density within the context window.

5. Guardrail Injection — the fetched text is wrapped in a strict directive (see guardrail.py):

   • Answer only from <verified_context>.

   • If unanswerable, reply exactly: "I cannot find a verified source for this information."

   • Cite every claim in brackets like [Source: ...].

   • Never fall back to pre-trained knowledge.

6. Local-Only — the server uses the stdio transport, so all processing stays on your machine.

📦 Project Structure

🧰 Requirements

• Python 3.10+

• Internet access (for the free search/scrape)

🔧 Tool Reference

fetch_verified_context(query: str, max_results: int = 3) -> str

🐛 Troubleshooting

• command not found: factanchor-mcp → you used Option A but didn't pip install -e ., or your venv isn't on PATH. Use Option B (script path) instead.

• Pages return only short snippets (first run) → Chromium is still installing in the background. Wait ~1–2 minutes and retry; subsequent runs are instant.

• "Browser executable doesn't exist" on Linux → install OS deps once: sudo playwright install-deps chromium (or sudo apt install libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1 libasound2).

• Rate-limit system note from the tool → DuckDuckGo is throttling free search. Wait a few minutes and retry. The server never crashes; it returns a clean system note for the LLM.

• Tool not appearing in client → restart the client fully after editing the config, and check its MCP/Developer panel for errors.

📈 Virality Strategy

• Before vs After video (X/Twitter & LinkedIn): show the assistant hallucinating a fake npm feature, then enable FactAnchor-MCP and watch it correctly say "I cannot find a verified source for this information." Tag @AnthropicAI with #MCP and #AI.

• Open-source launch: submit to the official MCP servers list and awesome-mcp collections.

📊 Evaluation

The "~80%" figure is an informal estimate. A small, hand-runnable eval set lives in eval/sample_queries.json — see eval/README.md for how to reproduce it. Contributions of more queries (or a CI assertion) are very welcome.

🤝 Contributing

See CONTRIBUTING.md. Keep it zero-cost and local-first.

📋 Success Metrics (v1.0)

⚠️ Honesty note: The "~80% reduction" is an informal estimate from manual testing against a small set of factual queries (see eval/sample_queries.json) — it is not a benchmarked or statistically validated result. The guardrail is a prompt directive, not a hard infrastructure constraint, so an LLM can occasionally drift from it in long conversations. FactAnchor reduces hallucination but does not eliminate it; always verify critical claims against the cited sources.

• 🧪 Up to ~80% fewer made-up facts observed in informal test queries.

• ✅ <3 min user setup time (clone → install → config).

• ✅ ₹0.00 server maintenance bill.

📜 License

MIT © FactAnchor-MCP contributors.