Skip to content
Back to search

lean-lsp-mcp

Lean Theorem Prover MCP

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ooo0ooo--lean-lsp-mcp/badge.svg)](/listings/ooo0ooo--lean-lsp-mcp)

HTML

<a href="/listings/ooo0ooo--lean-lsp-mcp"><img src="/api/listings/ooo0ooo--lean-lsp-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Overview

1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), a Python package manager. 2. Make sure your Lean project builds quickly by running `lake build` manually. 3. Configure your IDE/Setup 4. (Optional, highly recommended) Install [ripgrep](https://github.com/BurntSushi/ripgrep?tab=readme-ov-file#installation) (`rg`) for local search and source scanning (`lean_verify` warnings).

1. Install uv

[Install uv](https://docs.astral.sh/uv/getting-started/installation/) for your system. On Linux/MacOS: `curl -LsSf https://astral.sh/uv/install.sh | sh`

1b. Alternative: Install with Nix

If you use Nix, you can install the package directly from GitHub:

nix profile install github:oOo0oOo/lean-lsp-mcp

Or run it without installing: `nix run github:oOo0oOo/lean-lsp-mcp`.

This provides the MCP server only. You still need a Lean toolchain (`elan`/`lake`) for your project, same as the `uv` setup below.

2. Run `lake build`

`lean-lsp-mcp` will run `lake serve` in the project root to use the language server (for most tools). Some clients (e.g. Cursor) might timeout during this process. Therefore, it is recommended to run `lake build` manually before starting the MCP. This ensures a faster build time and avoids timeouts.

3. Configure your IDE/Setup

<details> <summary><b>VSCode (Click to expand)</b></summary> One-click config setup:

OR using the setup wizard:

Ctrl+Shift+P > "MCP: Add Server..." > "Command (stdio)" > "uvx lean-lsp-mcp" > "lean-lsp" (or any name you like) > Global or Workspace

OR manually adding config by opening `mcp.json` with:

Ctrl+Shift+P > "MCP: Open User Configuration"

and adding the following

{
    "servers": {
        "lean-lsp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "lean-lsp-mcp"
            ]
        }
    }
}

If you installed VSCode on Windows and are using WSL2 as your development environment, you may need to use this config instead:

{
    "servers": {
        "lean-lsp": {
            "type": "stdio",
            "command": "wsl.exe",
            "args": [
                "uvx",
                "lean-lsp-mcp"
            ]
        }
    }
}

If that doesn't work, you can try cloning this repository and replace `"lean-lsp-mcp"` with `"/path/to/cloned/lean-lsp-mcp"`.

</details>

<details> <summary><b>Cursor (Click to expand)</b></summary> 1. Open MCP Settings (File > Preferences > Cursor Settings > MCP)

2. "+ Add a new global MCP Server" > ("Create File")

3. Paste the server config into `mcp.json` file:

{
    "mcpServers": {
        "lean-lsp": {
            "command": "uvx",
            "args": ["lean-lsp-mcp"]
        }
    }
}

</details>

<details> <summary><b>Claude Code (Click to expand)</b></summary> Run one of these commands in the root directory of your Lean project (where `lakefile.toml` is located):

# Local-scoped MCP server
claude mcp add lean-lsp uvx lean-lsp-mcp

# OR project-scoped MCP server
# (creates or updates a .mcp.json file in the current directory)
claude mcp add lean-lsp -s project uvx lean-lsp-mcp

You can find more details about MCP server configuration for Claude Code [here](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#configure-mcp-servers). </details>

<details> <summary><b>Mistral Vibe (Click to expand)</b></summary> (These instructions cover Mac/Linux.)

1. Edit `~/.vibe/config.toml`.

2. Paste the following into the file (e.g. at the end):

[[mcp_servers]]
name = "lean-lsp"
transport = "stdio"
command = "uvx"
args = ["lean-lsp-mcp"]
tool_timeout_sec = 600

If there are no existing MCP servers, you may have to remove `mcp_servers = []`. </details>

4. Install ripgrep (optional but recommended)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 495 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">
  2. lean-lsp-mcp
  3. </h1>
  4. <h3 align="center">Lean Theorem Prover MCP</h3>
  5. <p align="center">
  6. <a href="https://pypi.org/project/lean-lsp-mcp/">
  7. <img src="https://img.shields.io/pypi/v/lean-lsp-mcp.svg" alt="PyPI version" />
  8. </a>
  9. <a href="">
  10. <img src="https://img.shields.io/github/last-commit/oOo0oOo/lean-lsp-mcp" alt="last update" />
  11. </a>
  12. <a href="https://github.com/oOo0oOo/lean-lsp-mcp/blob/master/LICENSE">
  13. <img src="https://img.shields.io/github/license/oOo0oOo/lean-lsp-mcp.svg" alt="license" />
  14. </a>
  15. </p>
  16. MCP server that allows agentic interaction with the [Lean theorem prover](https://lean-lang.org/) via the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/) using [leanclient](https://github.com/oOo0oOo/leanclient). This server provides a range of tools for LLM agents to understand, analyze and interact with Lean projects.
  17. ## Key Features
  18. * **Rich Lean Interaction**: Access diagnostics, goal states, term information, hover documentation and more.
  19. * **External Search Tools**: Use `LeanSearch`, `Loogle`, `Lean Finder` and `Lean Hammer` to find relevant theorems and definitions.
  20. * **Easy Setup**: Simple configuration for various clients, including VSCode, Cursor and Claude Code.
  21. ## Setup
  22. ### Overview
  23. 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), a Python package manager.
  24. 2. Make sure your Lean project builds quickly by running `lake build` manually.
  25. 3. Configure your IDE/Setup
  26. 4. (Optional, highly recommended) Install [ripgrep](https://github.com/BurntSushi/ripgrep?tab=readme-ov-file#installation) (`rg`) for local search and source scanning (`lean_verify` warnings).
  27. ### 1. Install uv
  28. [Install uv](https://docs.astral.sh/uv/getting-started/installation/) for your system. On Linux/MacOS: `curl -LsSf https://astral.sh/uv/install.sh | sh`
  29. ### 1b. Alternative: Install with Nix
  30. If you use Nix, you can install the package directly from GitHub:
  31. ```bash
  32. nix profile install github:oOo0oOo/lean-lsp-mcp
  33. ```
  34. Or run it without installing: `nix run github:oOo0oOo/lean-lsp-mcp`.
  35. This provides the MCP server only. You still need a Lean toolchain (`elan`/`lake`) for your project, same as the `uv` setup below.
  36. ### 2. Run `lake build`
  37. `lean-lsp-mcp` will run `lake serve` in the project root to use the language server (for most tools). Some clients (e.g. Cursor) might timeout during this process. Therefore, it is recommended to run `lake build` manually before starting the MCP. This ensures a faster build time and avoids timeouts.
  38. ### 3. Configure your IDE/Setup
  39. <details>
  40. <summary><b>VSCode (Click to expand)</b></summary>
  41. One-click config setup:
  42. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=lean-lsp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22lean-lsp-mcp%22%5D%7D)
  43. [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=lean-lsp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22lean-lsp-mcp%22%5D%7D&quality=insiders)
  44. OR using the setup wizard:
  45. Ctrl+Shift+P > "MCP: Add Server..." > "Command (stdio)" > "uvx lean-lsp-mcp" > "lean-lsp" (or any name you like) > Global or Workspace
  46. OR manually adding config by opening `mcp.json` with:
  47. Ctrl+Shift+P > "MCP: Open User Configuration"
  48. and adding the following
  49. ```jsonc
  50. {
  51. "servers": {
  52. "lean-lsp": {
  53. "type": "stdio",
  54. "command": "uvx",
  55. "args": [
  56. "lean-lsp-mcp"
  57. ]
  58. }
  59. }
  60. }
  61. ```
  62. If you installed VSCode on Windows and are using WSL2 as your development environment, you may need to use this config instead:
  63. ```jsonc
  64. {
  65. "servers": {
  66. "lean-lsp": {
  67. "type": "stdio",
  68. "command": "wsl.exe",
  69. "args": [
  70. "uvx",
  71. "lean-lsp-mcp"
  72. ]
  73. }
  74. }
  75. }
  76. ```
  77. If that doesn't work, you can try cloning this repository and replace `"lean-lsp-mcp"` with `"/path/to/cloned/lean-lsp-mcp"`.
  78. </details>
  79. <details>
  80. <summary><b>Cursor (Click to expand)</b></summary>
  81. 1. Open MCP Settings (File > Preferences > Cursor Settings > MCP)
  82. 2. "+ Add a new global MCP Server" > ("Create File")
  83. 3. Paste the server config into `mcp.json` file:
  84. ```jsonc
  85. {
  86. "mcpServers": {
  87. "lean-lsp": {
  88. "command": "uvx",
  89. "args": ["lean-lsp-mcp"]
  90. }
  91. }
  92. }
  93. ```
  94. </details>
  95. <details>
  96. <summary><b>Claude Code (Click to expand)</b></summary>
  97. Run one of these commands in the root directory of your Lean project (where `lakefile.toml` is located):
  98. ```bash
  99. # Local-scoped MCP server
  100. claude mcp add lean-lsp uvx lean-lsp-mcp
  101. # OR project-scoped MCP server
  102. # (creates or updates a .mcp.json file in the current directory)
  103. claude mcp add lean-lsp -s project uvx lean-lsp-mcp
  104. ```
  105. You can find more details about MCP server configuration for Claude Code [here](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#configure-mcp-servers).
  106. </details>
  107. <details>
  108. <summary><b>Mistral Vibe (Click to expand)</b></summary>
  109. (These instructions cover Mac/Linux.)
  110. 1. Edit `~/.vibe/config.toml`.
  111. 2. Paste the following into the file (e.g. at the end):
  112. ```toml
  113. [[mcp_servers]]
  114. name = "lean-lsp"
  115. transport = "stdio"
  116. command = "uvx"
  117. args = ["lean-lsp-mcp"]
  118. tool_timeout_sec = 600
  119. ```
  120. If there are no existing MCP servers, you may have to remove `mcp_servers = []`.
  121. </details>
  122. ### 4. Install ripgrep (optional but recommended)
  123. For the local search tool `lean_local_search`, install [ripgrep](https://github.com/BurntSushi/ripgrep?tab=readme-ov-file#installation) (`rg`) and make sure it is available in your PATH.
  124. ### 5. Install the Lean 4 skill (optional but recommended)
  125. With any agentic coding platform such as Claude Code or Codex, you can install the [Agentic Coding Skill: Lean 4 Theorem Proving](https://github.com/cameronfreer/lean4-skills/). This skill provides additional prompts and templates for interacting with Lean 4 projects, including guidance on using `lean-lsp-mcp`.
  126. ## MCP Tools
  127. ### List of available tools
  128. See [Tools documentation](docs/tools.md) for the full list of available tools.
  129. ### Disabling Tools
  130. Many clients allow the user to disable specific tools manually (e.g. lean_build).
  131. **VSCode**: Click on the Wrench/Screwdriver icon in the chat.
  132. **Cursor**: In "Cursor Settings" > "MCP" click on the name of a tool to disable it (strikethrough).
  133. You can also disable tools at server startup:
  134. - `LEAN_MCP_DISABLED_TOOLS`: Comma-separated tool names (for example `lean_run_code,lean_build`).
  135. - `LEAN_MCP_INSTRUCTIONS`: Replacement server instructions string.
  136. - `LEAN_MCP_TOOL_DESCRIPTIONS`: JSON object to override tool descriptions.
  137. Example:
  138. ```bash
  139. export LEAN_MCP_DISABLED_TOOLS="lean_run_code,lean_build"
  140. export LEAN_MCP_INSTRUCTIONS="Prefer lean_local_search before remote search tools."
  141. export LEAN_MCP_TOOL_DESCRIPTIONS='{"lean_goal":"Primary proof-state inspection tool."}'
  142. ```
  143. ## MCP Configuration
  144. This MCP server works out-of-the-box without any configuration. However, a few optional settings are available.
  145. ### Environment Variables
  146. - `LEAN_LOG_LEVEL`: Log level for the server. Options are "INFO", "WARNING", "ERROR", "NONE". Defaults to "INFO".
  147. - `LEAN_LOG_FILE_CONFIG`: Config file path for logging, with priority over `LEAN_LOG_LEVEL`. If not set, logs are printed to stdout.
  148. - `LEAN_PROJECT_PATH`: Path to your Lean project root. A valid Lean project root must contain `lean-toolchain` and either `lakefile.lean` or `lakefile.toml`. Relative `file_path` arguments resolve against this root. This variable is required for `streamable-http` and `sse`.
  149. - `LEAN_MCP_DISABLED_TOOLS`: Comma-separated list of tool names to remove from MCP tool listing.
  150. - `LEAN_MCP_INSTRUCTIONS`: Replacement server instructions string.
  151. - `LEAN_MCP_TOOL_DESCRIPTIONS`: JSON object mapping tool names to replacement descriptions.
  152. - `LEAN_MCP_SCRATCH_SLOTS`: Number of parallel scratch documents used for snippet
  153. trials. Defaults to `1`; increase it only when parallel attempts are worth the
  154. additional Lean process memory.
  155. - `LEAN_MCP_MAX_OUTPUT_CHARS`: Per-field character budget for goal states and
  156. diagnostic messages. Defaults to `6000`; oversized text is elided from the
  157. middle so both the local context and the goal target survive. Set to `0` to
  158. return everything untruncated.
  159. - `LEAN_REPL`: Set to `true`, `1`, or `yes` to enable fast REPL-based `lean_run_code` and line-based `lean_multi_attempt` (see [REPL Setup](#repl-setup)).
  160. - `LEAN_REPL_PATH`: Path to the `repl` binary. Auto-detected from `.lake/packages/repl/` or `.lake/packages/REPL/` if not set.
  161. - `LEAN_REPL_TIMEOUT`: Per-command timeout in seconds (default: 60).
  162. - `LEAN_REPL_MEM_MB`: Memory budget per REPL in MiB (default: 16384). Linux uses a kernel address-space limit (respecting any lower inherited hard limit). macOS samples resident memory of the REPL process tree every 100 ms and kills the group on excess; brief overshoot between samples is possible. Windows does not enforce this budget.
  163. - `LEAN_LSP_MCP_TOKEN`: Secret token for bearer authentication when using `streamable-http` or `sse` transport. If set, bearer auth is required for every request.
  164. - `LEAN_BUILD_CONCURRENCY`: Build concurrency mode for `lean_build`. Options: `allow` (default), `cancel`, `share`.
  165. - `LEAN_HAMMER_URL`: URL for a self-hosted [Lean Hammer Premise Search](https://github.com/hanwenzhu/lean-premise-server) instance. Rate limits are skipped when set to a custom backend.
  166. - `LEAN_LOOGLE_LOCAL`: Set to `true`, `1`, or `yes` to enable local loogle (see [Local Loogle](#local-loogle) section).
  167. - `LEAN_LOOGLE_MODULE`: Root module for local Loogle (default: `Mathlib`). Use a built module such
  168. as `Init` or `Mathlib.Data.Nat.Basic` to search it and its imports with a smaller index. Indices
  169. are separated by project and module.
  170. - `LEAN_LOOGLE_LOCAL_ONLY`: Set to `true`, `1`, or `yes` to refuse remote Loogle fallback when local
  171. search is unavailable. Defaults to false; this does not disable other remote search tools.
  172. - `LEAN_LOOGLE_CACHE_DIR`: Override the cache directory for local loogle (default: `~/.cache/lean-lsp-mcp/loogle`).
  173. - `LOOGLE_URL`: URL for a self-hosted Loogle instance (default: `https://loogle.lean-lang.org`). Rate limits are skipped when set to a custom backend.
  174. - `LOOGLE_HEADERS`: JSON object of extra HTTP headers for Loogle requests (e.g. `'{"X-API-Key": "..."}'`).
  175. You can also often set these environment variables in your MCP client configuration:
  176. <details>
  177. <summary><b>VSCode mcp.json Example</b></summary>
  178. ```jsonc
  179. {
  180. "servers": {
  181. "lean-lsp": {
  182. "type": "stdio",
  183. "command": "uvx",
  184. "args": [
  185. "lean-lsp-mcp"
  186. ],
  187. "env": {
  188. "LEAN_PROJECT_PATH": "/path/to/your/lean/project",
  189. "LEAN_LOG_LEVEL": "NONE"
  190. }
  191. }
  192. }
  193. }
  194. ```
  195. </details>
  196. ### Transport Methods
  197. The Lean LSP MCP server supports the following transport methods:
  198. - `stdio`: Standard input/output (default)
  199. - `streamable-http`: HTTP streaming
  200. - `sse`: Server-sent events (MCP legacy, use `streamable-http` if possible)
  201. `stdio` supports project inference and switching as you move between Lean projects. `streamable-http` and `sse` are single-project deployments: they require `LEAN_PROJECT_PATH` at startup and reject tool-driven project switching.
  202. You can specify the transport method using the `--transport` argument when running the server. For `sse` and `streamable-http` you can also optionally specify the host and port:
  203. ```bash
  204. uvx lean-lsp-mcp --transport stdio # Default transport
  205. uvx lean-lsp-mcp --transport streamable-http # Available at http://127.0.0.1:8000/mcp
  206. uvx lean-lsp-mcp --transport sse --host localhost --port 12345 # Available at http://localhost:12345/sse
  207. uvx lean-lsp-mcp --version # Print the installed version
  208. ```
  209. ### Protocol compatibility and runtime
  210. This release uses the official Python MCP SDK 2.2.0. The same server supports
  211. 2026-07-28 discovery and request metadata as well as legacy initialization;
  212. clients do not need a separate endpoint. Tool names, arguments, structured
  213. results, and text fallbacks are unchanged. Expected tool errors retain actionable
  214. messages; unexpected crash details stay in server logs. Tool configuration is read at startup
  215. (CLI options override environment variables); restart to change it. The tool
  216. catalog is sorted by name and carries a private 60-second cache hint for modern
  217. clients.
  218. Streamable HTTP uses the SDK's bounded request-body and legacy-session defaults.
  219. Expired sessions must reconnect; modern requests do not need session IDs. Keep
  220. streaming responses enabled for long-running build progress. A modern request
  221. must opt in before receiving MCP log notifications; stderr/file logging remains
  222. controlled by `LEAN_LOG_LEVEL` and the logging configuration.
  223. Build and analysis tools execute project or supplied Lean code, which can have
  224. I/O effects even when scratch documents leave source files unchanged. Their MCP
  225. annotations therefore make no read-only or idempotence promise. Use trusted
  226. projects and code.
  227. ### OpenAI Secure MCP Tunnel
  228. For ChatGPT, Codex, Responses API, or other OpenAI surfaces, use [OpenAI Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) instead of exposing `lean-lsp-mcp` to the public internet. Create a tunnel in [Platform tunnel settings](https://platform.openai.com/settings/organization/tunnels), then run `tunnel-client` on a host that can reach your Lean project:
  229. ```bash
  230. export CONTROL_PLANE_API_KEY="sk-..."
  231. tunnel-client init \
  232. --sample sample_mcp_stdio_local \
  233. --profile lean-lsp-local \
  234. --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  235. --mcp-command "uvx lean-lsp-mcp --transport stdio --lean-project-path /path/to/lean/project"
  236. tunnel-client doctor --profile lean-lsp-local --explain
  237. tunnel-client run --profile lean-lsp-local
  238. ```
  239. Use `--lean-project-path` so relative `file_path` arguments resolve inside the intended Lean project. For HTTP, bind `lean-lsp-mcp` to loopback and use `--mcp-server-url http://127.0.0.1:8000/mcp` in the tunnel profile:
  240. ```bash
  241. export LEAN_PROJECT_PATH="/path/to/lean/project"
  242. uvx lean-lsp-mcp --transport streamable-http --host 127.0.0.1 --port 8000
  243. ```
  244. Keep `tunnel-client run` healthy while testing connector discovery or tool calls. In ChatGPT connector settings, choose **Tunnel** as the connection type.
  245. ### Bearer Token Authentication
  246. Transport via `streamable-http` and `sse` supports bearer token authentication. For private OpenAI access, prefer OpenAI Secure MCP Tunnel; bearer auth remains available for HTTP/SSE deployments that clients reach directly.
  247. Set the `LEAN_LSP_MCP_TOKEN` environment variable (or see section 3 for setting env variables in MCP config) to a secret token before starting the server. If this variable is set, requests without a matching `Authorization: Bearer ...` header are rejected before tool dispatch.
  248. Example Linux/MacOS setup:
  249. ```bash
  250. export LEAN_LSP_MCP_TOKEN="your_secret_token"
  251. uvx lean-lsp-mcp --transport streamable-http
  252. ```
  253. Clients should then include the token in the `Authorization` header. This is an
  254. opaque secret checked by this server, not an OAuth access token. The compatibility
  255. mode explicitly disables SDK OAuth resource/audience validation; it does not
  256. provide an OAuth authorization server or per-user permissions.
  257. ### REPL Setup
  258. Enable fast REPL-based `lean_run_code` and line-based `lean_multi_attempt`. Uses [leanprover-community/repl](https://github.com/leanprover-community/repl) tactic mode. Exact `column`-based attempts still use the LSP path.
  259. **1. Add REPL to your Lean project's `lakefile.toml`:**
  260. ```toml
  261. [[require]]
  262. name = "repl"
  263. git = "https://github.com/leanprover-community/repl"
  264. rev = "v4.35.0" # Use a REPL tag compatible with your Lean toolchain
  265. ```
  266. **2. Build it:**
  267. ```bash
  268. lake build repl
  269. ```
  270. **3. Enable via CLI or environment variable:**
  271. ```bash
  272. uvx lean-lsp-mcp --repl
  273. # Or via environment variable
  274. export LEAN_REPL=true
  275. ```
  276. The REPL binary is auto-detected from `.lake/packages/repl/` or
  277. `.lake/packages/REPL/`. Falls back to LSP if not found.
  278. ### Path Policy
  279. File-based tools only operate on files inside the active Lean project, resolved `.lake/packages/*` dependencies, and the Lean stdlib source tree. Returned file paths are sanitized to avoid leaking host absolute paths:
  280. - Project files are returned relative to the project root, for example `src/MyFile.lean`.
  281. - Dependency files are returned under `.lake/packages/<package>/...`.
  282. - Stdlib files are returned under `.lean-stdlib/...`.
  283. Symlink escapes outside those roots are rejected.
  284. ### Local Loogle
  285. Run Loogle locally to avoid the remote API's rate limit (3 req/30s). The binary is built once for the project's Lean toolchain. The first Mathlib index takes a few minutes; subsequent starts load it in seconds.
  286. ```bash
  287. # Enable via CLI
  288. uvx lean-lsp-mcp --loogle-local
  289. # Or via environment variable
  290. export LEAN_LOOGLE_LOCAL=true
  291. ```
  292. **Requirements:** `git`, `lake` ([elan](https://github.com/leanprover/elan)), a built Mathlib project, and substantial memory for indexing. In measurements on current Mathlib, the initial index used ~13 GiB peak RSS and a warm load used ~7 GiB.
  293. **Note:** Local loogle is currently only supported on Unix systems (Linux/macOS). Windows users should use WSL or the remote API.
  294. **Mathlib comes from your project:** `--lean-project-path` must point at a built project that depends on Mathlib. The local binary is compiled for that project's Lean toolchain and runs through `lake env`, so Lake supplies the project's own dependency environment. Loogle's native dependency hash detects changed `.olean` files and rebuilds a stale index automatically.
  295. Falls back to remote API if local loogle fails.
  296. ## Notes on MCP Security
  297. There are many valid security concerns with the Model Context Protocol (MCP) in general!
  298. This MCP server is meant as a research tool and is currently in beta.
  299. While it does not handle any sensitive data such as passwords or API keys, it still includes various security risks:
  300. - Access to your local file system.
  301. - Powerful local build and analysis capabilities.
  302. - External network access for remote search tools unless disabled by the operator.
  303. Please be aware of these risks. Feel free to audit the code and report security issues!
  304. ### Containerized setup (recommended for stricter isolation)
  305. Build image:
  306. ```bash
  307. docker build -t lean-lsp-mcp:containerized .
  308. ```
  309. Run with a mounted project root (read-only source + writable Lake cache):
  310. ```bash
  311. docker run --rm -i \
  312. -v "$PWD":/workspace:ro \
  313. -v lean-lsp-mcp-lake-cache:/workspace/.lake \
  314. lean-lsp-mcp:containerized
  315. ```
  316. The included Docker image defaults to:
  317. - `LEAN_PROJECT_PATH=/workspace`
  318. - `LEAN_MCP_DISABLED_TOOLS=lean_run_code`
  319. Notes:
  320. - `LEAN_MCP_DISABLED_TOOLS` is a startup default and can be overridden by `docker run -e`.
  321. - Using `--network none` can break tools that require network access (`leansearch`, `loogle`, `leanfinder`, `hammer_premise`) and dependency downloads.
  322. - The entrypoint exits immediately if `LEAN_PROJECT_PATH` does not exist.
  323. For more information, you can use [Awesome MCP Security](https://github.com/Puliczek/awesome-mcp-security) as a starting point.
  324. ## Development
  325. See [Adding a new tool](docs/adding-a-tool.md) for a step-by-step guide to implementing a new MCP tool (return models, helper modules, registration, tests, and docs).
  326. ### MCP Inspector
  327. ```bash
  328. npx @modelcontextprotocol/inspector uvx --with-editable path/to/lean-lsp-mcp python -m lean_lsp_mcp.server
  329. ```
  330. ### Run Tests
  331. ```bash
  332. uv sync --all-extras
  333. uv run pytest tests
  334. ```
  335. ## Publications and Formalization Projects using lean-lsp-mcp
  336. - Ax-Prover: A Deep Reasoning Agentic Framework for Theorem Proving in Mathematics and Quantum Physics [arxiv](https://arxiv.org/abs/2510.12787)
  337. - Numina-Lean-Agent: An Open and General Agentic Reasoning System for Formal Mathematics [arxiv](https://arxiv.org/abs/2601.14027) [github](https://github.com/project-numina/numina-lean-agent)
  338. - MerLean: An Agentic Framework for Autoformalization in Quantum Computation [arxiv](https://arxiv.org/pdf/2602.16554)
  339. - M2F: Automated Formalization of Mathematical Literature at Scale [arxiv](https://arxiv.org/pdf/2602.17016)
  340. - A Group-Theoretic Approach to Shannon Capacity of Graphs and a Limit Theorem from Lattice Packings [github](https://github.com/jzuiddam/GroupTheoreticShannonCapacity/)
  341. ## Talks
  342. lean-lsp-mcp: Tools for agentic interaction with Lean (Lean Together 2026) [youtube](https://www.youtube.com/watch?v=uttbYaTaF-E)
  343. ## Related Projects
  344. - [LeanTool](https://github.com/GasStationManager/LeanTool)
  345. - [LeanExplore MCP](https://www.leanexplore.com/docs/mcp)
  346. ## License & Citation
  347. **MIT** licensed. See [LICENSE](LICENSE) for more information.
  348. Citing this repository is highly appreciated but not required by the license.
  349. ```bibtex
  350. @software{lean-lsp-mcp,
  351. author = {Oliver Dressler},
  352. title = {{Lean LSP MCP: Tools for agentic interaction with the Lean theorem prover}},
  353. url = {https://github.com/oOo0oOo/lean-lsp-mcp},
  354. month = {3},
  355. year = {2025}
  356. }
  357. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.