footnote-mcp

footnote-mcp — web research MCP server with claim verification

Search, extract data, and verify every claim against the source page.

Unlike search APIs (Tavily, Exa) or scrapers (Firecrawl) that return raw text or markdown, footnote-mcp is built for verification: every claim is checked against the raw source text with sentence-level citations and character offsets, with zero required API keys.

Add to Cursor · Claude Desktop setup

Runs without API keys · 45 tools · MIT licensed

Quick start

pip install footnote-mcppython -m playwright install chromium   # browser tier for JS-heavy and blocked pages

footnote-mcp speaks MCP over stdio. Point a client at it — Claude Desktop's claude_desktop_config.json, or Cursor's ~/.cursor/mcp.json:

{"mcpServers": {"footnote": {"command": "footnote-mcp"}}}

No API keys are needed to start. Restart the client and ask it to run startup_health_check: it reports, one line each, whether the extractors, the PDF and spreadsheet parsers, the browser, OCR and the cache directory are usable on this machine — so a missing optional piece shows up now rather than halfway through a research task.

Search the web without configuring an API key

Ask the assistant to look something up and web_search queries the zero-key providers — Bing, DuckDuckGo, Brave, Wiby — alongside any keyed provider you configured, then deduplicates and merges them into one ranking.

Every result carries the engines that returned it, so a page two independent indexes agree on is distinguishable from one only a single engine found, and a relevance score. Snippets count as discovery only: nothing at this stage is evidence yet, which is what the next two sections are for.

Provider routing, keys, and semantic reranking: docs/search-backends.md.

Extract tables and files from a page into structured rows

web_extract_tables turns a page's HTML tables into named columns and rows, each set tagged with the URL it came from and with the true total, so a truncated answer says so instead of looking complete. Point it at a Wikipedia revenue table and you get Rank, Name, Industry, Revenue, Employees as fields you can sort and compare, not a wall of text to re-read.

Data a page links rather than renders is covered too: web_detect_downloads finds the CSV/TSV/XLS/XLSX/PDF/JSON attached to it, web_parse_file parses them, and web_fetch_json takes an API endpoint directly.

Verify that a source actually supports a claim

The part a plain search tool does not do. evidence_entailment compares a claim to the source text and returns a verdict; corroborate_claim triangulates across excerpts, and locate_claim_span returns the supporting sentence with character offsets.

Given the claim "Norway's battery-electric share of new passenger cars was 82.4% in 2023" and a source reading "In 2023, battery-electric vehicles accounted for 82.4% of all new passenger cars registered in Norway", the verdict comes back as a value your agent can act on rather than a paragraph it has to interpret:

{"status": "supported", "score": 0.778, "reason": "token overlap heuristic", "backend": "heuristic"}

The default backend is deterministic and offline, and it never quietly hands the decision to another model: where it is not confident it returns needs_review with the spans it matched, for you — or the assistant that called it, which already has both texts — to read. A local LLM judge (backend="ollama") and a local NLI model (backend="local_nli") are there when you want them. Measured accuracy of the deterministic path, which is the default: benchmarks/REPORT.md.

How it works

Search snippets are discovery, never evidence. Discovery merges several independent indexes; fetching escalates through a ladder — plain HTTP, optional proxy, headless Chromium, optional hosted scrape API — and stops at the cheapest tier returning real content. Extraction pulls text, tables, and linked files, each cached with its source URL. Only then does verification run, checking the claim against the fetched text before it counts. web_deep_search wraps the whole loop: it decomposes requirements, re-searches unresolved gaps, and returns an evidence ledger with a funnel showing where candidates were lost.

query → merged discovery → fetch ladder → extract (text · tables · files) → verify vs source → evidence

Requirements

• Python 3.10 or newer, on macOS, Linux or Windows — CI runs all six combinations
• Chromium via python -m playwright install chromium, for the browser tier and browser tools
• Any MCP client speaking stdio; config is documented for Claude Desktop and Cursor
• Optional, for semantic: true: an Ollama daemon, or requirements-embed.txt to run the same bge-m3 weights in-process — the only option where no daemon exists, such as Docker
• Optional: the system tesseract binary for OCR in web_screenshot and scanned PDFs
• No API keys, no account, no hosted service

Limitations

• The offline entailment heuristic scores 100% on numeric and factual claims but 83% overall on the labelled set; purely semantic negation and paraphrase need backend="ollama".
• The benchmark runner has no hard per-task timeout on Windows: it is built on signal.setitimer, which Windows lacks, so a hung task there runs unguarded. The server itself is unaffected.
• Zero-key providers are scraped, so results vary by IP. A refused search retries through a proxy and, for Bing and Brave, headless Chromium; DuckDuckGo answers Chromium with an error stub, so there it is cooldown or nothing.
• Semantic reranking is best-effort: with no embedding runtime reachable, the original ranking is returned unchanged.
• Generated recipes run in a subprocess that may import only csv, datetime, html, json, math, re and statistics, with eval, exec, open and __import__ rejected — a validator, not a hardened sandbox.
• The hosted HTTP server holds per-user rate limits in memory; they reset on restart.

Configuration

The server takes one flag, --headed, which shows the Chromium window instead of running it invisibly — useful for watching the browser tier work on a page that keeps failing:

{"mcpServers": {"footnote": {"command": "footnote-mcp", "args": ["--headed"]}}}

Environment variables

Every variable is optional. The free tier (Bing, DuckDuckGo, Brave, Wiby) answers first; metered providers are called only when free results fall below FOOTNOTE_MIN_FREE_RESULTS. Paid search is the fallback, not the default: without keys, most queries are unaffected, and only narrow or obscure searches stay thin rather than being topped up.

Full list and defaults: .env.example, docs/fetching.md, docs/search-backends.md.

docker run -i --rm ghcr.io/kazkozdev/footnote-mcp:latest   # bundles Chromium and Tesseract

{"mcpServers": {"footnote": {"command": "docker",  "args": ["run", "-i", "--rm", "ghcr.io/kazkozdev/footnote-mcp:latest"]}}}

uvx footnote-mcppipx install footnote-mcppython3 -m venv .venv && source .venv/bin/activate && pip install -e .

python -m pytest -q                              # offline; no network or keysRUN_LIVE_WEB_TESTS=1 python -m pytest -m live    # opt-in live search