Mathematica MCP

A front-end / notebook automation layer for Mathematica, built for AI agents.

A local MCP server that lets an AI agent drive a live Mathematica session: run code, create and edit notebooks, capture screenshots, verify derivations, and read .nb files without a kernel. Works with Claude, Cursor, VS Code, Codex, and Gemini.

It is designed to run beside the official Wolfram Local MCP, not to replace it: Wolfram's server is the reference Wolfram-Language evaluator and documentation surface; this one is the notebook / front-end automation layer. See How it compares.

v1.0 is a breaking release. The default profile is now lean (12 tools) instead of full (82 tools). Set MATHEMATICA_PROFILE=classic (or full) to keep the old surface, and reinstall the Mathematica addon. See the Migration Guide. v1.1 bumps the addon protocol to 4 (honest evaluation_pending status for front-end evaluations): re-run setup or wolframscript -file addon/install.wl after upgrading, then restart Mathematica.

Watch it in action

An AI agent solving math, generating plots, and controlling a live Mathematica notebook. Errors are returned directly to the agent, no copy-pasting notebook output back into chat.

Why This Exists

LLMs can write Mathematica code, but they can't run it, control a live notebook, or verify their own results. This MCP server bridges that gap:

• Live notebook control: create, edit, evaluate, and screenshot Mathematica notebooks directly from your AI agent.
• License-free notebook reading: read_notebook_file reads .nb files even when no kernel or Mathematica license is available (Python-native fallback parser; a kernel is used for higher fidelity when present, and is required for .wl scripts).
• Warm execution: computation runs on a persistent headless kernel session that starts warming in the background the moment the server launches, so the agent's calls return in sub-second time instead of paying a cold wolframscript start-up on every request.
• Error-aware execution: Mathematica messages are fed back to the agent with a suggested_fix and, where a correction can be derived, a concrete retry_with call, so it can debug without you copying notebook output into chat.
• Local and private: core execution runs on your machine. Optional tools like wolfram_alpha and repository search contact Wolfram's cloud services only when invoked.

The lean default

v1.0 ships a consolidated 12-tool surface as the default profile: status, notebooks, cells, edit_cells, evaluate, screenshot, verify_derivation, kernel, vars, read_notebook_file, guide, and batch. It exposes ~11.5 KB of tool schema (~2.9k tokens) versus ~61 KB / ~15k tokens for the old 82-tool surface - roughly a 5x cut in the context the agent pays before it does any work. Each tool is a thin wrapper over the exact internals the classic surface uses.

Prefer the old surface? classic (alias full) keeps all 82 legacy tools byte-identical to pre-1.0, and MATHEMATICA_TOOLSETS adds opt-in extras (data I/O, cloud, graphics, ...) to lean without switching profiles.

• Full tool reference with parameters and action enums: Technical Reference - Lean Profile Tools
• All profiles and opt-in toolsets: Technical Reference - Tool Profiles
• How execution stays fast (warm persistent kernel, error guidance, Mathematica 15 notes): Technical Reference - Architecture

How it compares

This server runs alongside the official Wolfram Local MCP (tool names per the MCPServer paclet docs) - setup <client> --with-official writes the official server's config next to this one so they run side by side. Overlap is deliberate where it helps agents; the differentiator is notebook / front-end automation that runs without a license round trip.

ReadNotebook / WriteNotebook overlap the notebook tools here, but the official ReadNotebook runs through a kernel; read_notebook_file parses the .nb directly in Python, so an agent can read notebooks with no license consumed and no kernel start-up.

Quick Start

From install to first working notebook plot in under 2 minutes.

Prerequisites

1. Mathematica 14.0+ (15+ recommended) with wolframscript in your PATH

   • Download Mathematica
   • macOS: add to ~/.zshrc: export PATH="/Applications/Mathematica.app/Contents/MacOS:$PATH"

2. uv package manager

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

One-Command Setup

The PyPI package and CLI are named mathematica-mcp-full (unchanged in 1.0 - the name predates the lean default).

# For Claude Desktop
uvx mathematica-mcp-full setup claude-desktop

# For Cursor
uvx mathematica-mcp-full setup cursor

# For VS Code (requires GitHub Copilot Chat extension)
uvx mathematica-mcp-full setup vscode

# For OpenAI Codex CLI
uvx mathematica-mcp-full setup codex

# For Google Gemini CLI
uvx mathematica-mcp-full setup gemini

# For Claude Code CLI
uvx mathematica-mcp-full setup claude-code

# Optional: pick a profile (default is "lean")
uvx mathematica-mcp-full setup claude-desktop --profile classic

Then restart Mathematica and your editor. Done!

bash <(curl -sSL https://raw.githubusercontent.com/AbhiRawat4841/mathematica-mcp/main/install.sh)

Verify Installation

uvx mathematica-mcp-full doctor

Tip: If you encounter errors after updating, clear the cache:

uv cache clean mathematica-mcp-full && uvx mathematica-mcp-full setup <client>

What You Can Ask For

"Integrate x^2 sin(x) from 0 to pi, then verify the result."

evaluate("Integrate[x^2 Sin[x], {x, 0, Pi}]")   =>  -4 + Pi^2
verify_derivation(steps=["Integrate[x^2 Sin[x], {x, 0, Pi}]", "-4 + Pi^2"])
=> Step 1 → 2: ✓ VALID
   All steps are valid!

"Plot the sombrero function in a new notebook."

notebooks(action="create", title="Sombrero")
evaluate("Plot3D[Sinc[Sqrt[x^2+y^2]], {x,-4,4}, {y,-4,4}]", target="notebook")
=> [3D surface plot rendered in the live notebook]

"Read the derivation in this notebook without opening Mathematica."

read_notebook_file("paper/derivation.nb", mode="markdown")
=> [structured markdown; works even with no kernel or license available]

Who This Is For

Manual Installation

For full details, troubleshooting, and advanced configuration, see the Installation Guide.

Documentation

• Migration Guide (0.9.x → 1.0): breaking default-profile change and old→new tool mapping
• Technical Reference: Architecture, tools, and configuration
• Security Model: Threat model, permissions, and vulnerability reporting
• Benchmarks: Performance data and reproduction steps
• Contributing: Development setup, testing, and PR process
• Changelog: Version history
• Examples: Polished agent session walkthroughs

License

MIT License