Footnote MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Footnote MCP listing page.
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
footnote-mcp speaks MCP over stdio. Point a client at it — Claude Desktop's
claude_desktop_config.json, or Cursor's ~/.cursor/mcp.json:
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:
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.
All 45 tools by category
Search (8)
web_search— Multi-engine search across zero-key providers (Bing, DuckDuckGo, Brave, Wiby) and optional metered APIsweb_search_recent— Search restricted to a recency window (day, week, month, year)web_deep_search— Iterative multi-step research loop with evidence ledger and funnel diagnosticspapers_search— Academic paper search via Crossref and arXivencyclopedia_search— Wikipedia and Wikidata entity lookup plus read-only SPARQLgithub_search— Search public repositories, code, issues, and commitsarchive_search— Historical snapshots via Wayback Machine and Common Crawlgenerate_search_queries— Generate targeted operator queries (site:,filetype:csv)
Fetch (4)
web_read— Fetch URL, extract text, evaluate source quality, and cache snapshotweb_fetch_authenticated— Fetch pages requiring custom cookies or session headersweb_archive_fetch— Retrieve the nearest Wayback Machine snapshot for dead or changed URLsweb_crawl— Breadth-first crawl following links from a starting URL
Extract (15)
web_extract_tables— Parse HTML tables into typed columns and rows with source URLsweb_detect_downloads— Discover linked data files (CSV, TSV, XLS, XLSX, PDF, JSON, XML)web_parse_file— Download and parse tabular data and PDF documentsweb_fetch_json— Fetch direct REST API endpoints into parsed JSONcheck_date_completeness— Validate time series date continuity across calendar and market schedulesresolve_units— Normalize currencies, units, and currency pairsvalidate_unit_rows— Detect and reject rows with conflicting units or currenciesreconcile_time_series— Align series by key, compute deltas, and flag missing entries or outliersexport_dataset— Save consolidated rows to CSV, XLSX, or JSON filestool_spec_propose— Propose task-specific extraction recipe specificationstool_code_generate— Generate starter Python extraction recipestool_code_validate— Validate recipe code against an AST safety allowlisttool_code_run_sandboxed— Execute extraction code inside a restricted subprocesstool_promote— Persist validated recipes to local memoryrecipe_registry— List, inspect, run, and delete registered extraction recipes
Verify (8)
evidence_entailment— Evaluate whether source text entails a claim (heuristic, Ollama, or NLI)corroborate_claim— Triangulate claim consensus or conflict across multiple excerptslocate_claim_span— Locate supporting sentences with character offsets and containment scoresclassify_source— Classify domains (official, aggregator, blog, forum, interactive, blocked)source_cache_get— Retrieve cached page snapshots and provenance metadatasource_cache_put— Store page contents and metadata into persistent cachebuild_research_debug_report— Compact diagnostic report of queries, sources, and verification gapsstartup_health_check— Inspect availability of parsers, browser runtime, OCR, and cache directories
Browser (10)
web_navigate— Open URL in Chromium session (headless or--headed)web_snapshot— Inspect interactive DOM accessibility tree with stable element referencesweb_click— Click interactive page elements by reference ID or CSS selectorweb_type— Enter text into form fields and input elementsweb_scroll— Scroll viewports or containers to reveal dynamic contentweb_extract— Extract targeted HTML elements or attributesweb_screenshot— Capture page screenshots with optional Tesseract OCRbrowser_set_date_range— Manipulate dynamic web date-picker controlsbrowser_extract_tables— Extract client-side rendered tables after DOM hydrationbrowser_extract_tables_for_date_range— Automate date selection and table extraction cycles
Full parameters and schemas: docs/tools.md.
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, orrequirements-embed.txtto run the same bge-m3 weights in-process — the only option where no daemon exists, such as Docker - Optional: the system
tesseractbinary for OCR inweb_screenshotand 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,reandstatistics, witheval,exec,openand__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:
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.
| Variable | Effect when set | Effect when unset |
|---|---|---|
FOOTNOTE_SEARXNG_URL | Self-hosted SearXNG joins the free tier, unmetered | Free tier is Bing, DuckDuckGo, Brave, Wiby |
TAVILY_API_KEY | Tavily joins the metered rotation | Skipped; never called |
BRAVE_API_KEY | Brave Search API joins the rotation, alongside scraped Brave | Only the scraped, keyless Brave is used |
GOOGLE_API_KEY and GOOGLE_CSE_ID | Google Programmable Search joins the rotation | Skipped; never called |
FOOTNOTE_MIN_FREE_RESULTS | Free results threshold to trigger metered fallback | 3 |
FOOTNOTE_PROVIDER_STRATEGY | merge calls all providers; cost_aware calls metered only if needed | cost_aware |
GITHUB_TOKEN | github_search runs at authenticated rate limits | Unauthenticated rate limits |
FOOTNOTE_RESEARCH_MODEL | Ollama model for query planning and fact extraction in web_deep_search | Runs without planner |
FOOTNOTE_EMBED_MODEL | Embedding model for semantic: true reranking | bge-m3 |
FOOTNOTE_EMBED_BACKEND | ollama needs the daemon; local loads the same weights in-process (requirements-embed.txt) | auto: daemon if running, else in-process, else ranking is unchanged |
FOOTNOTE_BROWSER_FALLBACK | 0 disables Chromium browser fallback | Enabled |
FOOTNOTE_SEARCH_CACHE_TTL | Search cache TTL in seconds (0 disables) | 86400 |
FOOTNOTE_PROXIES | Comma-separated proxy URLs for requests | Direct connections |
FOOTNOTE_SCRAPE_API | Hosted scraper fallback (firecrawl or scrapingbee) with key | Browser tier is last fallback |
FOOTNOTE_SOURCE_CACHE | Directory for raw cached pages | ~/.footnote-mcp/source_cache/ |
Full list and defaults: .env.example, docs/fetching.md, docs/search-backends.md.
Docker, uvx, from source, OCR, tests
Docker
uvx / pipx / from source
None of these fetch the browser. Run python -m playwright install chromium once as well, or
the browser tier and the browser tools are unavailable.
OCR and local NLI
pytesseract needs the system binary (brew install tesseract). evidence_entailment with
backend="local_nli" needs pip install -r requirements-nli.txt and FOOTNOTE_NLI_MODEL.
