{
"markdown": "# footnote-mcp — web research MCP server with claim verification\n\nSearch, extract data, and verify every claim against the source page.\n\nUnlike 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.\n\n[Add to Cursor](https://cursor.com/install-mcp?name=footnote&config=eyJjb21tYW5kIjoiZm9vdG5vdGUtbWNwIn0%3D) · [Claude Desktop setup](#quick-start)\n\n\n\nRuns without API keys · 45 tools · MIT licensed\n\n\n\n\n\n## Quick start\n\n```bash\npip install footnote-mcp\npython -m playwright install chromium # browser tier for JS-heavy and blocked pages\n```\n\n`footnote-mcp` speaks MCP over stdio. Point a client at it — Claude Desktop's\n`claude_desktop_config.json`, or Cursor's `~/.cursor/mcp.json`:\n\n```json\n{\"mcpServers\": {\"footnote\": {\"command\": \"footnote-mcp\"}}}\n```\n\nNo API keys are needed to start. Restart the client and ask it to run `startup_health_check`:\nit reports, one line each, whether the extractors, the PDF and spreadsheet parsers, the\nbrowser, OCR and the cache directory are usable on this machine — so a missing optional piece\nshows up now rather than halfway through a research task.\n\n## Search the web without configuring an API key\n\nAsk the assistant to look something up and `web_search` queries the zero-key providers — Bing,\nDuckDuckGo, Brave, Wiby — alongside any keyed provider you configured, then deduplicates and\nmerges them into one ranking.\n\nEvery result carries the engines that returned it, so a page two independent indexes agree on\nis distinguishable from one only a single engine found, and a relevance score. Snippets count\nas discovery only: nothing at this stage is evidence yet, which is what the next two sections\nare for.\n\nProvider routing, keys, and semantic reranking: [docs/search-backends.md](docs/search-backends.md).\n\n## Extract tables and files from a page into structured rows\n\n`web_extract_tables` turns a page's HTML tables into named columns and rows, each set tagged\nwith the URL it came from and with the true total, so a truncated answer says so instead of\nlooking complete. Point it at a Wikipedia revenue table and you get `Rank`, `Name`,\n`Industry`, `Revenue`, `Employees` as fields you can sort and compare, not a wall of text to\nre-read.\n\nData a page links rather than renders is covered too: `web_detect_downloads` finds the\nCSV/TSV/XLS/XLSX/PDF/JSON attached to it, `web_parse_file` parses them, and `web_fetch_json`\ntakes an API endpoint directly.\n\n## Verify that a source actually supports a claim\n\nThe part a plain search tool does not do. `evidence_entailment` compares a claim to the source\ntext and returns a verdict; `corroborate_claim` triangulates across excerpts, and\n`locate_claim_span` returns the supporting sentence with character offsets.\n\nGiven the claim *\"Norway's battery-electric share of new passenger cars was 82.4% in 2023\"*\nand a source reading *\"In 2023, battery-electric vehicles accounted for 82.4% of all new\npassenger cars registered in Norway\"*, the verdict comes back as a value your agent can act\non rather than a paragraph it has to interpret:\n\n```json\n{\"status\": \"supported\", \"score\": 0.778, \"reason\": \"token overlap heuristic\", \"backend\": \"heuristic\"}\n```\n\nThe default backend is deterministic and offline, and it never quietly hands the decision to\nanother model: where it is not confident it returns `needs_review` with the spans it matched,\nfor you — or the assistant that called it, which already has both texts — to read. A local\nLLM judge (`backend=\"ollama\"`) and a local NLI model (`backend=\"local_nli\"`) are there when you\nwant them. Measured accuracy of the deterministic path, which is the default:\n[benchmarks/REPORT.md](benchmarks/REPORT.md).\n\n## How it works\n\nSearch snippets are discovery, never evidence. Discovery merges several independent indexes;\nfetching escalates through a ladder — plain HTTP, optional proxy, headless Chromium, optional\nhosted scrape API — and stops at the cheapest tier returning real content. Extraction pulls\ntext, tables, and linked files, each cached with its source URL. Only then does verification\nrun, checking the claim against the fetched text before it counts. `web_deep_search` wraps the\nwhole loop: it decomposes requirements, re-searches unresolved gaps, and returns an evidence\nledger with a funnel showing where candidates were lost.\n\n```\nquery → merged discovery → fetch ladder → extract (text · tables · files) → verify vs source → evidence\n```\n\n\nAll 45 tools by category
\n\n### Search (8)\n- `web_search` — Multi-engine search across zero-key providers (Bing, DuckDuckGo, Brave, Wiby) and optional metered APIs\n- `web_search_recent` — Search restricted to a recency window (day, week, month, year)\n- `web_deep_search` — Iterative multi-step research loop with evidence ledger and funnel diagnostics\n- `papers_search` — Academic paper search via Crossref and arXiv\n- `encyclopedia_search` — Wikipedia and Wikidata entity lookup plus read-only SPARQL\n- `github_search` — Search public repositories, code, issues, and commits\n- `archive_search` — Historical snapshots via Wayback Machine and Common Crawl\n- `generate_search_queries` — Generate targeted operator queries (`site:`, `filetype:csv`)\n\n### Fetch (4)\n- `web_read` — Fetch URL, extract text, evaluate source quality, and cache snapshot\n- `web_fetch_authenticated` — Fetch pages requiring custom cookies or session headers\n- `web_archive_fetch` — Retrieve the nearest Wayback Machine snapshot for dead or changed URLs\n- `web_crawl` — Breadth-first crawl following links from a starting URL\n\n### Extract (15)\n- `web_extract_tables` — Parse HTML tables into typed columns and rows with source URLs\n- `web_detect_downloads` — Discover linked data files (CSV, TSV, XLS, XLSX, PDF, JSON, XML)\n- `web_parse_file` — Download and parse tabular data and PDF documents\n- `web_fetch_json` — Fetch direct REST API endpoints into parsed JSON\n- `check_date_completeness` — Validate time series date continuity across calendar and market schedules\n- `resolve_units` — Normalize currencies, units, and currency pairs\n- `validate_unit_rows` — Detect and reject rows with conflicting units or currencies\n- `reconcile_time_series` — Align series by key, compute deltas, and flag missing entries or outliers\n- `export_dataset` — Save consolidated rows to CSV, XLSX, or JSON files\n- `tool_spec_propose` — Propose task-specific extraction recipe specifications\n- `tool_code_generate` — Generate starter Python extraction recipes\n- `tool_code_validate` — Validate recipe code against an AST safety allowlist\n- `tool_code_run_sandboxed` — Execute extraction code inside a restricted subprocess\n- `tool_promote` — Persist validated recipes to local memory\n- `recipe_registry` — List, inspect, run, and delete registered extraction recipes\n\n### Verify (8)\n- `evidence_entailment` — Evaluate whether source text entails a claim (heuristic, Ollama, or NLI)\n- `corroborate_claim` — Triangulate claim consensus or conflict across multiple excerpts\n- `locate_claim_span` — Locate supporting sentences with character offsets and containment scores\n- `classify_source` — Classify domains (official, aggregator, blog, forum, interactive, blocked)\n- `source_cache_get` — Retrieve cached page snapshots and provenance metadata\n- `source_cache_put` — Store page contents and metadata into persistent cache\n- `build_research_debug_report` — Compact diagnostic report of queries, sources, and verification gaps\n- `startup_health_check` — Inspect availability of parsers, browser runtime, OCR, and cache directories\n\n### Browser (10)\n- `web_navigate` — Open URL in Chromium session (headless or `--headed`)\n- `web_snapshot` — Inspect interactive DOM accessibility tree with stable element references\n- `web_click` — Click interactive page elements by reference ID or CSS selector\n- `web_type` — Enter text into form fields and input elements\n- `web_scroll` — Scroll viewports or containers to reveal dynamic content\n- `web_extract` — Extract targeted HTML elements or attributes\n- `web_screenshot` — Capture page screenshots with optional Tesseract OCR\n- `browser_set_date_range` — Manipulate dynamic web date-picker controls\n- `browser_extract_tables` — Extract client-side rendered tables after DOM hydration\n- `browser_extract_tables_for_date_range` — Automate date selection and table extraction cycles\n\nFull parameters and schemas: [docs/tools.md](docs/tools.md).\n\n \n\n## Requirements\n\n- Python 3.10 or newer, on macOS, Linux or Windows — CI runs all six combinations\n- Chromium via `python -m playwright install chromium`, for the browser tier and browser tools\n- Any MCP client speaking stdio; config is documented for Claude Desktop and Cursor\n- 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\n- Optional: the system `tesseract` binary for OCR in `web_screenshot` and scanned PDFs\n- No API keys, no account, no hosted service\n\n## Limitations\n\n- 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\"`.\n- 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.\n- 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.\n- Semantic reranking is best-effort: with no embedding runtime reachable, the original ranking is returned unchanged.\n- 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.\n- The hosted HTTP server holds per-user rate limits in memory; they reset on restart.\n\n## Configuration\n\nThe server takes one flag, `--headed`, which shows the Chromium window instead of running it\ninvisibly — useful for watching the browser tier work on a page that keeps failing:\n\n```json\n{\"mcpServers\": {\"footnote\": {\"command\": \"footnote-mcp\", \"args\": [\"--headed\"]}}}\n```\n\n### Environment variables\n\nEvery 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.\n\n| Variable | Effect when set | Effect when unset |\n|---|---|---|\n| `FOOTNOTE_SEARXNG_URL` | Self-hosted SearXNG joins the free tier, unmetered | Free tier is Bing, DuckDuckGo, Brave, Wiby |\n| `TAVILY_API_KEY` | Tavily joins the metered rotation | Skipped; never called |\n| `BRAVE_API_KEY` | Brave Search API joins the rotation, alongside scraped Brave | Only the scraped, keyless Brave is used |\n| `GOOGLE_API_KEY` **and** `GOOGLE_CSE_ID` | Google Programmable Search joins the rotation | Skipped; never called |\n| `FOOTNOTE_MIN_FREE_RESULTS` | Free results threshold to trigger metered fallback | `3` |\n| `FOOTNOTE_PROVIDER_STRATEGY` | `merge` calls all providers; `cost_aware` calls metered only if needed | `cost_aware` |\n| `GITHUB_TOKEN` | `github_search` runs at authenticated rate limits | Unauthenticated rate limits |\n| `FOOTNOTE_RESEARCH_MODEL` | Ollama model for query planning and fact extraction in `web_deep_search` | Runs without planner |\n| `FOOTNOTE_EMBED_MODEL` | Embedding model for `semantic: true` reranking | `bge-m3` |\n| `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 |\n| `FOOTNOTE_BROWSER_FALLBACK` | `0` disables Chromium browser fallback | Enabled |\n| `FOOTNOTE_SEARCH_CACHE_TTL` | Search cache TTL in seconds (`0` disables) | `86400` |\n| `FOOTNOTE_PROXIES` | Comma-separated proxy URLs for requests | Direct connections |\n| `FOOTNOTE_SCRAPE_API` | Hosted scraper fallback (`firecrawl` or `scrapingbee`) with key | Browser tier is last fallback |\n| `FOOTNOTE_SOURCE_CACHE` | Directory for raw cached pages | `~/.footnote-mcp/source_cache/` |\n\nFull list and defaults: [.env.example](.env.example), [docs/fetching.md](docs/fetching.md), [docs/search-backends.md](docs/search-backends.md).\n\n\nDocker, uvx, from source, OCR, tests
\n\n### Docker\n\n```bash\ndocker run -i --rm ghcr.io/kazkozdev/footnote-mcp:latest # bundles Chromium and Tesseract\n```\n\n```json\n{\"mcpServers\": {\"footnote\": {\"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"ghcr.io/kazkozdev/footnote-mcp:latest\"]}}}\n```\n\n### uvx / pipx / from source\n\n```bash\nuvx footnote-mcp\npipx install footnote-mcp\npython3 -m venv .venv && source .venv/bin/activate && pip install -e .\n```\n\nNone of these fetch the browser. Run `python -m playwright install chromium` once as well, or\nthe browser tier and the browser tools are unavailable.\n\n### OCR and local NLI\n\n`pytesseract` needs the system binary (`brew install tesseract`). `evidence_entailment` with\n`backend=\"local_nli\"` needs `pip install -r requirements-nli.txt` and `FOOTNOTE_NLI_MODEL`.\n\n### Tests\n\n```bash\npython -m pytest -q # offline; no network or keys\nRUN_LIVE_WEB_TESTS=1 python -m pytest -m live # opt-in live search\n```\n\n \n\n
\n\n\n\n \n\n[](https://github.com/KazKozDev/footnote-mcp/actions/workflows/tests.yml) [](https://pypi.org/project/footnote-mcp/) [](pyproject.toml) [](LICENSE)\n\n[Issues](https://github.com/KazKozDev/footnote-mcp/issues) · [LICENSE](LICENSE) · [Tools](docs/tools.md) · [Hosting](docs/hosting.md) · [Benchmarks](benchmarks/REPORT.md) · [LinkedIn](https://www.linkedin.com/in/kazkozdev)\n\n
\n\n",
"bytes": 15107,
"sha": "1e4803fe756cccc01019f4cff15857f6ee719751328a29b8f9e42bedfae8e32c",
"repo_slug": "kazkozdev/footnote-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_kazkozdev_footnote_mcp_6c103995/readme"
}