footnote-mcp 0.2.6

An MCP server for source-grounded web research. It searches the web, fetches and extracts pages, pulls structured data out of tables/files/APIs, and — the part that sets it apart — verifies that a claim is actually supported by its source instead of trusting a snippet. 45 tools over stdio MCP, driven by any MCP client (Claude Desktop, Cursor) or by the companion Scholiast research agent.

The design priority is trustworthiness over convenience: search snippets are treated as discovery only, every fetched page is cached with provenance, and claims are checked against the source text before they count. It also degrades gracefully — with no API keys and no config it still works (scraped search + an automatic headless-browser fallback + an offline verification heuristic); keys and env vars only make it better.

Quick start

From PyPI (Python ≥ 3.10):

pip install footnote-mcp
python -m playwright install chromium   # the headless browser used by the fetch fallback
footnote-mcp                            # start the server (speaks MCP over stdio)

Or from source:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .                        # installs the `footnote-mcp` console script + deps
python -m playwright install chromium   # the headless browser used by the fetch fallback
footnote-mcp                            # start the server (speaks MCP over stdio)

footnote-mcp now waits for an MCP client on stdio. Point a client at it by dropping this into its MCP settings (Claude Desktop: claude_desktop_config.json; Cursor: ~/.cursor/mcp.json):

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

Hosted MCP endpoint (Render)

This repository also includes an authenticated Streamable HTTP deployment. The stdio command above remains the recommended local option; the hosted endpoint is for MCP clients that support remote servers.

1. Push this repository to GitHub, then create a Render Blueprint from it. Render reads render.yaml, builds the included Dockerfile (including Chromium and Tesseract), and exposes the health check at /healthz.
2. Choose a unique service name, then set FOOTNOTE_MCP_PUBLIC_URL in Render to its exact public origin, for example https://my-footnote-mcp.onrender.com. FOOTNOTE_MCP_API_KEY is generated by the Blueprint; it is the owner key. Keep it secret and use it only for administration/testing.
3. Connect an MCP client to https://my-footnote-mcp.onrender.com/mcp with:

Authorization: Bearer <FOOTNOTE_MCP_API_KEY>

The API key is required: a public, unauthenticated research and browser server would let strangers consume its outbound traffic and call its tools. The service also validates its configured public host and browser Origin to protect the MCP endpoint from DNS rebinding.

Render Free is suitable for demos, not production: it sleeps after 15 minutes of inactivity, cold starts take about a minute, and both outbound bandwidth and instance hours are limited. The filesystem is ephemeral, so do not rely on the source cache or browser profile persisting across restarts.

Giving access to other people

Never distribute the owner key. Create a separate random key for each person:

python -m footnote_mcp.keygen

Then update FOOTNOTE_MCP_API_KEYS in Render's Environment settings and redeploy. Its value is JSON, where each user has a key and a personal requests-per-minute limit:

{
  "alice": {"key": "fn_alice_key_here", "rpm": 20},
  "bob": {"key": "fn_bob_key_here", "rpm": 10}
}

Give each person only their own value. To revoke access, remove that user from the JSON and redeploy; the other keys keep working. Limits are held in memory, which is appropriate for this one-instance Free service and reset on restart.

No API keys are required to start — search falls back to zero-key Bing, DuckDuckGo, Brave, and Wiby discovery. Add keys later under "env" (see Search backends). Pass --headed to watch the browser tier work.

Optional runtime variables are documented in .env.example. Copy it to .env for local shells, or paste selected variables into your MCP client config:

{
  "mcpServers": {
    "footnote": {
      "command": "footnote-mcp",
      "env": {
        "TAVILY_API_KEY": "..."
      }
    }
  }
}

To run without installing, straight from the source tree:

PYTHONPATH=src python -m footnote_mcp

Verifying claims — the differentiator

The reason to use this over a plain search tool is evidence_entailment and friends: they tell a claim a source supports from one it does not. benchmarks/run_benchmark.py measures that on a labeled set of claim/source pairs (and demos corroborate_claim and locate_claim_span):

python benchmarks/run_benchmark.py                    # offline heuristic (deterministic)
python benchmarks/run_benchmark.py --backend ollama   # LLM judge (needs ollama)

Offline-heuristic result on the labeled set (benchmarks/REPORT.md):

On its design domain — numeric and factual data claims — the offline heuristic never blesses an unsupported claim and never misses one. Its blind spot is purely-semantic negation/paraphrase; for those, evidence_entailment with backend="ollama" (a local LLM judge) closes the gap. Run the --backend ollama line above to score that path on your own machine.

Tools

Search backends

web_search routes through a provider layer. A configured zero-key SearXNG instance is tried first, followed by keyed providers and finally zero-key Bing, DuckDuckGo, Brave, and Wiby. Marginalia remains available as an explicit provider. Results are normalized to one shape regardless of backend. Every provider is relevance-filtered and deduplicated before cross-provider merging; repeated URLs from the same provider do not receive an agreement bonus.

auto (default) queries every configured provider plus the latency-bounded zero-key fallbacks and merges the complete result set. Marginalia is excluded from auto because its shared public endpoint can be slow; use provider="auto+marginalia" to include it in the merged search, or provider="marginalia" to isolate it. Force one isolated backend with the provider argument (searxng/tavily/brave/google/wiby/marginalia/scrape). Brave and DuckDuckGo enter a temporary cooldown after rate limiting; override the defaults with FOOTNOTE_BRAVE_COOLDOWN_SECONDS and FOOTNOTE_DDG_COOLDOWN_SECONDS.

Specialized zero-key discovery

The public MCP surface is organized by user intent rather than by HTTP API:

All four return title, url, snippet, published, authors, source, and source_type where those fields apply. web_deep_search accepts an optional sources array (web, papers, encyclopedia, github, archive). With an empty array it always uses general web discovery and adds specialized sources when the query signals their intent.

web_deep_search is a separate, slower research loop. Set model (or FOOTNOTE_RESEARCH_MODEL) to enable requirement decomposition, gap-specific query planning, and strict fact extraction. It maintains a serializable research state and evidence ledger, expands fetch/chunk budgets across iterations, parses HTML tables and linked CSV/XLS/XLSX/PDF/JSON files, and verifies subject, metric, period, value, and unit against an exact source quote before admitting an item. The result includes answer_ready, unresolved requirements, per-iteration diagnostics, and the cumulative funnel candidates → deduplicated_documents → relevant_documents → successful_fetches → extracted_facts → verified_evidence.

Semantic reranking. Pass semantic: true to web_search to reorder by meaning rather than keyword overlap: it over-fetches, embeds query and results with a local ollama model, and sorts by cosine similarity (each result gains semantic_score). Best-effort — if ollama is unavailable the original order is returned. Model: FOOTNOTE_EMBED_MODEL (default bge-m3).

Fetching & anti-bot ladder

web_read fetches through an escalation ladder (scraper.py): the cheapest method runs first and escalates only when a result looks blocked or empty. A block/quality detector decides when to escalate; a per-domain rate limiter, circuit breaker, and negative cache keep it polite. The tier used and the full attempt trace come back in fetch_tier / scrape_tiers.

With nothing configured it is the plain HTTP path plus an automatic browser fallback for JavaScript-rendered pages.

The rate limit, circuit breaker and negative cache apply to every outbound request, not only to pages fetched through the ladder: they live in politeness.py and are taken inside fetch._get, which each tool's HTTP call funnels through. A 429 or 503 is waited out (honoring Retry-After) rather than retried immediately; web_crawl stops at the first refusal; and parallel fetching runs across hosts, never several workers at one host.

Runtime data

~/.footnote-mcp/source_cache/        # persistent page cache (with provenance)
~/.footnote-mcp/source_cache/http/   # ETag/Last-Modified bodies for conditional requests
~/.footnote-mcp/research_memory.json # persistent research memory

Override the cache location with FOOTNOTE_SOURCE_CACHE=/path/to/cache footnote-mcp.

check_date_completeness supports the calendars calendar, business_day, crypto_24_7, forex_weekday, us_business_day, and ru_business_day (pass explicit holidays for source-specific ones; the us_/ru_ variants use the optional holidays package).

Other install paths

Docker bundles Chromium and tesseract — nothing else to install:

docker build -t footnote-mcp .
docker run -i --rm footnote-mcp        # the client launches this; see MCP config below

Published images are available from GitHub Container Registry:

docker run -i --rm ghcr.io/kazkozdev/footnote-mcp:0.2.6
docker run -i --rm ghcr.io/kazkozdev/footnote-mcp:latest

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

pipx / uvx (isolated install of the entry point):

pipx install /path/to/footnote-mcp          # or: pipx install git+<repo-url>
uvx --from /path/to/footnote-mcp footnote-mcp   # ad-hoc, no install

OCR. PDF/image OCR uses pytesseract + the system tesseract binary (brew install tesseract on macOS). Local NLI backend for evidence_entailment backend="local_nli": pip install -r requirements-nli.txt (model via FOOTNOTE_NLI_MODEL). Either way, startup_health_check reports what is actually available. Runtime dependency ranges are declared in pyproject.toml and mirrored in requirements.txt.

Tests

pip install -r requirements-dev.txt
python -m pytest -q          # offline unit + smoke tests; no network or keys needed

tests/test_mcp_smoke.py launches the server over real MCP stdio and exercises the tools end to end against a local HTTP fixture; the rest are offline unit tests of the parsers, fetch ladder, search providers, and dispatch. The live search test is opt-in:

RUN_LIVE_WEB_TESTS=1 python -m pytest -m live

CI runs the same suite (.github/workflows/tests.yml).

License

MIT — see LICENSE.