A local-first Model Context Protocol (MCP) server that exposes a research-mathematics arXiv corpus to multi-agent Claude pipelines. arXMCP is the substrate a Claude sketcher → autoformalizer → tactician → fixer workflow shares — every sub-agent uses the same MCP endpoint to fetch grounded context (theorem statements, proofs, lemma references, citation neighborhoods) from a single, version-pinned corpus.
Target arXiv categories: math.AG, math.NT, math-ph, hep-th.
Run the long-running arxmcp-server; register the stateless arxmcp-shim
in Claude Code's ~/.claude.json; sub-agents then call MCP tools over
loopback 127.0.0.1:7733. The server exposes eight tools:
| Tool | Capability |
|---|---|
search_papers |
Dense ANN over BGE-M3 statement embeddings; level = theorem / section / paper; notebook + paper_id filters. |
get_chunk |
Direct LanceDB chunk lookup with a 256 KB inline cap + resource_link fallback. |
find_equation |
MathML → Zhang–Shasha tree-edit-distance fused with dense cosine; LaTeX falls back to dense-only. |
get_definitions |
Per-paper \newcommand / \DeclareMathOperator / \def notation table with term lookup. |
find_lemma_by_name |
SQLite FTS5 theorem-name index — exact → trigram → fuzzy Jaccard. |
get_paper |
Chunks-synthesized per-paper metadata. |
cite_neighbors |
Kùzu citation-graph traversal (cites / cited_by / depends_on, depth 1–2). |
lean_verify |
Verify a Lean 4 snippet against a managed local kernel (gated by ARXMCP_ENABLE_LEAN). |
Under the hood: a 3-tier retrieval cache (SQLite exact + FAISS semantic + LRU
rerank-set), per-session retrieval caps, a regex query router, a Kùzu
citation graph from OpenAlex + INSPIRE-HEP + intra-paper \ref{} chains, and
a loopback-only operator console at /ui/ for notebook management. Corpus
is organized into independently ingested notebooks; textbook PDFs ingest
via MinerU + LaTeXML. All transport is MCP 2025-06-18 Streamable HTTP,
loopback bind only.
# 1. bootstrap (Python ≥3.11): create venv, install deps, create var/ tree
python3 -m venv .venv && source .venv/bin/activate
make bootstrap
# 2. create a notebook and add papers (EMAIL persists the arXiv polite-pool
# contact so the server never needs ARXMCP_CONTACT_EMAIL)
make init NOTEBOOK=demo EMAIL=you@example.com
make add NOTEBOOK=demo PAPER=1309.4265
# 3. ingest, then serve it
make ingest ARGS="--paper-ids-file=tools/seed-papers.txt --limit=5"
ARXMCP_NOTEBOOK=demo make up # MCP server on 127.0.0.1:7733
# 4. register the stdio shim: merge this into ~/.claude.json
# {"mcpServers": {"arxmcp": {"command": "arxmcp-shim",
# "args": ["--server", "http://127.0.0.1:7733"]}}}make help lists every target. The Makefile is bash-only; on Windows run
the server with python -m server.main from the activated venv.
Install, usage, API and operations guides are moving to the wiki. Until a page lands there, its last version is in the archived tree.
Contributing: CONTRIBUTING.md · Security: SECURITY.md · Changes: CHANGES.md.
arXMCP/
├── server/ long-running MCP server (FastAPI + Streamable HTTP; indices + caches + /ui/ console)
├── ingest/ corpus pipeline (chunker, embedder, BM25, citation-graph ingest)
├── shim/ stateless stdio↔HTTP bridge registered in Claude Code's ~/.claude.json
├── ops/ operability layer (backup, cutover, restore drill, drift watchdog, cron/systemd units)
├── tools/ dev + ingest utilities (seed/notebook fetch, eval gates, ops reports)
├── tests/ pytest suite + retrieval-quality eval harness under tests/eval/
├── docker/ multi-stage Dockerfile (non-root, tini, HEALTHCHECK on /readyz)
├── infra/ deployment + observability manifests
├── apps/ desktop shell (Tauri supervisor + PyInstaller packaging)
└── var/ gitignored data tree (created by `make bootstrap`)
These never change:
- Local-first, single-user, single-workstation. No multi-host orchestration.
- Loopback-only bind.
127.0.0.1:7733. The server refuses to bind to0.0.0.0at config-parse time. - MCP 2025-06-18 Streamable HTTP transport. No SSE; single-shot
application/jsonresponses. - Math fidelity over retrieval recall. LaTeXML + MathML; never PyPDF as a primary parser.
MIT. © 2026 Chris Dare.
Working conventions for contributors and agents: CLAUDE.md.