LeanExplore

A search engine for Lean 4 declarations

A search engine for Lean 4 declarations. This project provides tools and resources for exploring the Lean 4 ecosystem.

The current indexed projects include:

• Batteries
• CSLib
• FLT (Fermat's Last Theorem)
• FormalConjectures
• Init
• Lean
• Mathlib
• PhysLean
• Std

Installation

The base package connects to the remote API and does not require heavy ML dependencies:

pip install lean-explore

To run the local search backend (which uses on-device embedding and reranking models), install the extra ML dependencies:

pip install lean-explore[local]

Then fetch the data files and start the local MCP server:

lean-explore data fetch
lean-explore mcp serve --backend local

Claude Code and Codex plugin

The repository includes a plugin for both Claude Code and Codex. It connects to the hosted MCP server, so it does not need a Python install, a local search index, account, API key, or browser authorization. The tools are available as soon as the plugin is installed.

The hosted endpoint allows 30 POST requests per client IP in any 60-second window. Protocol initialization and tool-discovery requests count toward the limit, and clients sharing a public IP share the same budget.

Agents should begin with the token-efficient search_summary tool, then use the per-field retrieval tools for the declarations they need. The older full-result search MCP tool is deprecated and remains only for compatibility. All LeanExplore MCP tools are read-only and cannot modify Lean packages or external systems.

In Claude Code:

/plugin marketplace add justincasher/lean-explore
/plugin install lean-explore@lean-explore
/reload-plugins

In Codex:

codex plugin marketplace add https://github.com/justincasher/lean-explore
codex plugin add lean-explore@lean-explore

Start a new Codex session after installation so the MCP tools are loaded.

Documentation

Full docs live in the docs/ folder, or at https://www.leanexplore.com/docs.

Page	Description
Getting Started	Install and run your first search.
CLI Reference	Every lean-explore command and flag.
MCP Server	Wire LeanExplore into Claude, Cursor, or any MCP client.
API Client	Use ApiClient from Python.
Local Search Backend	How hybrid BM25 + FAISS + reranking works.
Configuration	Environment variables and data layout.
Data Models	SearchResult, SearchResponse, and related types.
Extraction Pipeline	Rebuild the dataset from Lean source (contributors).

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on code style, testing, and development setup.

Cite

If you use LeanExplore in your research or work, please cite it as follows:

General Citation:

Justin Asher. (2025). LeanExplore: A search engine for Lean 4 declarations. https://arxiv.org/abs/2506.11085

BibTeX Entry:

@software{Asher_LeanExplore_2025,
  author = {Asher, Justin},
  title = {{LeanExplore: A search engine for Lean 4 declarations}},
  year = {2025},
  url = {https://arxiv.org/abs/2506.11085}
}

License

This code is distributed under an Apache License (see LICENSE).