mathematica-mcp

A zero-dependency MCP server that connects a locally installed Wolfram Language kernel (Mathematica or the free Wolfram Engine) to any Model Context Protocol client: Claude Desktop, Cursor, VS Code, Cline, DeepSeek Harness, or your own agent.

It starts a persistent math.exe / WolframKernel process on the same machine and exposes four tools over stdio JSON-RPC:

Variables and definitions survive between calls: a = 17 in one call, a + 1 in the next returns 18. Everything runs in a local kernel process — no cloud API, no API keys, no network requests.

• Runtime dependencies: none. Node.js ≥ 18 at runtime; no npm packages, no Wolfram paclet, no build step.

• Transport: newline-delimited JSON-RPC 2.0 (MCP stdio); stdout carries protocol frames only, diagnostics go to stderr.

• Kernel discovery: ordered candidate probing that skips unlicensed or broken installations and falls back to the next candidate.

mathematica-mcp/
├── bin/mathematica-mcp.js     # executable entry point (package.json "bin")
├── src/server.js              # MCP protocol, tool schemas, tool handlers
├── src/kernel.js              # kernel process bridge: queue, framing, timeouts, restart
├── src/detect.js              # kernel discovery + license/health probe
├── test/                      # node:test suite (skips kernel tests when no kernel is installed)
├── dsh/                       # DSH plugin bundle: MCP tools (vendors this server)
├── notebook/                  # DSH plugin: interactive sidebar notebook (Host + browser halves)
├── market/                    # DSH plugin-market index for these bundles
└── docs/                      # client setup, DSH install, notebook maintainers, publishing notes

Prior art (read this first)

This project is not the first Mathematica/Wolfram MCP integration, and it makes no claim to be first, only, or comprehensive. Related projects include:

• WolframResearch/AgentTools — Wolfram Research's official WL paclet that runs an MCP server from inside a Wolfram kernel. Install the paclet, then point an MCP client at its server.

• Zhen-WushuiLingchun/dsh-wolfram-bundle — an MIT-licensed DeepSeek Harness bundle that wraps AgentTools and exposes its tools in DSH.

• hatter123/dsh-wolfram — a minimal single-tool DSH plugin that calls wolframscript -code.

What this project adds, factually:

• a standalone Node MCP stdio server that works with any MCP client, with no Wolfram paclet, no npm install and no build step on the server side (zero runtime dependencies);

• persistent kernel state across tool calls, with a bridge-level timeout/restart/watchdog;

• graphics and data export (png, svg, pdf, csv, txt, json, tex) as a first-class tool;

• an optional DeepSeek Harness plugin bundle + plugin-market index in dsh/ and market/, which vendors the same server;

• a DeepSeek Harness sidebar notebook plugin in notebook/: an interactive Wolfram notebook with code cells, typeset output, real .nb files and agent edits — with its own kernel process (see the two-kernel note).

These projects are independent; this one is not affiliated with them.

Related MCP server: Mathematica MCP Server

Requirements

1. A locally licensed Mathematica or a free Wolfram Engine on the same machine. There is no cloud/API fallback: if no licensed kernel is found, the tools return an actionable error.

2. Node.js ≥ 18 to run the server (no packages to install).

3. For the optional DSH bundle: a DeepSeek Harness profile that ships @deepseek-ai/dsh-mcp-client (any standard profile does).

The server finds the kernel automatically. The first usable candidate wins; each candidate is probed by starting it and evaluating a trivial program, so unlicensed installs (No valid password found., exit code 69) and broken binaries are skipped:

1. --kernel <path> command-line argument (highest priority),

2. MATHEMATICA_EXE or MATHEMATICA_KERNEL environment variable,

3. ~/.mathematica-mcp.json with {"kernelPath": "<path>"},

4. well-known install locations, newest version first. On Windows, desktop ...\Wolfram\<ver>\math.exe and ...\Mathematica\<ver>\math.exe are preferred over ...\Wolfram Engine\<ver>\math.exe; math.exe is used rather than MathKernel.exe because only math.exe is a reliable stdio REPL.

Wolfram Engine is a first-class fallback. When Mathematica is not installed — or its kernel is unlicensed/unusable — probing continues with an activated Wolfram Engine and the MCP tools keep working with it. If a kernel that was already selected later disappears (for example Mathematica is removed or upgraded away), the cached selection is dropped and the next call re-detects candidates, so an activated Wolfram Engine can take over without restarting the MCP client. To prefer the Engine even when Mathematica is installed, point the server at it explicitly:

setx MATHEMATICA_EXE "C:\Program Files\Wolfram Research\Wolfram Engine\15.0\math.exe"

Example (Windows):

setx MATHEMATICA_EXE "C:\Program Files\Wolfram Research\Wolfram\15.0\math.exe"

Linux/macOS:

export MATHEMATICA_EXE="/usr/local/Wolfram/Mathematica/15.0/Executables/math"
export MATHEMATICA_EXE="/Applications/Mathematica.app/Contents/MacOS/WolframKernel"

Install and run

From a git clone

git clone https://github.com/yhbcode000/mathematica-mcp.git
cd mathematica-mcp
node bin/mathematica-mcp.js --version   # mathematica-mcp 0.1.1
node bin/mathematica-mcp.js --help

The server speaks MCP on stdin/stdout and is normally started by an MCP client, not by hand.

From npm (after publication)

npx -y mathematica-mcp
# or
npm install -g mathematica-mcp
mathematica-mcp --version

The npm package is zero-dependency; npx only downloads this package itself.

MCP client configuration

The server is a plain stdio MCP server. Use an absolute path to bin/mathematica-mcp.js (and an absolute node path if your GUI client does not inherit PATH). JSON configs below use forward slashes; on Windows both C:/... and escaped C:\\... are accepted.

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "mathematica": {
      "command": "node",
      "args": ["D:/tools/mathematica-mcp/bin/mathematica-mcp.js"],
      "env": {
        "MATHEMATICA_EXE": "C:/Program Files/Wolfram Research/Wolfram/15.0/math.exe"
      }
    }
  }
}

The env block is only needed when auto-detection does not find the kernel.

Cursor

.cursor/mcp.json in your project (or the global equivalent):

{
  "mcpServers": {
    "mathematica": {
      "command": "node",
      "args": ["D:/tools/mathematica-mcp/bin/mathematica-mcp.js"]
    }
  }
}

Generic stdio client

Any client that launches a command and speaks newline-delimited JSON-RPC 2.0 on its stdin/stdout can use the server:

{
  "command": "node",
  "args": ["/opt/mathematica-mcp/bin/mathematica-mcp.js", "--kernel", "/usr/local/Wolfram/Mathematica/15.0/Executables/math"],
  "cwd": "/opt/mathematica-mcp",
  "env": {}
}

See docs/mcp-clients.md for more client-specific notes.

DeepSeek Harness (DSH)

This repository also ships a companion DSH plugin bundle in dsh/ (dsh-mathematica-mcp). It vendors this server and inserts the shipped @deepseek-ai/dsh-mcp-client bridge, registering the tools as mcp__mathematica__mathematica_evaluate, mcp__mathematica__mathematica_export, mcp__mathematica__mathematica_kernel_status and mcp__mathematica__mathematica_information.

From a local checkout (no git required):

# 1. Copy bin/ + src/ into the bundle's vendored server directory
node dsh/scripts/sync-server.mjs

# 2. Ask the agent to install the bundle, or call plugin_manager with:
#    { "action": "install_bundle", "target": "<absolute path to checkout>/dsh" }

From the plugin market (requires git on PATH), add the raw index URL https://raw.githubusercontent.com/yhbcode000/mathematica-mcp/main/market/index.json in Discover and install Mathematica MCP.

Full install and manual cordis.patch.yml instructions: dsh/README.md and docs/dsh-install.md. Design notes: docs/architecture.md.

Sidebar notebook plugin (DeepSeek Harness)

This repository also ships a separate DSH plugin in notebook/: dsh-mathematica-notebook — an interactive Mathematica notebook docked in the DSH right sidebar, next to the chat. It is independent of the MCP server above; install either or both.

Requirements are the same as the MCP server: a locally licensed Mathematica or the free Wolfram Engine. Install it with plugin_manager install_bundle pointing at <checkout>/notebook, or from the same plugin-market index once released. Keep the vendored kernel bridge current with node notebook/scripts/sync-kernel.mjs.

Two kernels, not one. The notebook plugin starts and owns its own Wolfram kernel, separate from the kernel running inside the mcp__mathematica__* MCP server process. Definitions and state do not cross between them; each runs, times out and restarts independently, and each uses its own kernel process memory and license seat. Move data between the two through files.

Full user guide: notebook/README.md. Maintainer notes (RPC channel, .nb codec, revision model, native launcher, security, roadmap): docs/notebook-plugin.md.

Tool reference

Every tool result is a single MCP content block of type text whose text is a JSON object. Tool failures use isError: true (the MCP connection itself stays healthy).

mathematica_evaluate

Evaluate Wolfram Language code in the persistent kernel.

Example call:

{ "name": "mathematica_evaluate", "arguments": { "code": "Integrate[Sin[x]^2, {x, 0, Pi}] // N" } }

Example success result:

{
  "ok": true,
  "result": 1.5707963267948966,
  "result_inputform": "1.5707963267948966`",
  "output": "",
  "duration_ms": 12
}

Fields:

• result — decoded value when the result is a plain string or number (omitted for compound expressions).

• result_inputform — the raw Mathematica InputForm of the result; always present.

• output — text printed during the evaluation (e.g. Print[...]), when any.

• messages — message names such as Power::infy, when messages were generated.

• duration_ms — wall-clock duration of the call.

A syntax error or an aborted evaluation returns isError: true with error: "evaluation_failed" / error: "timeout", a human-readable message, and the kernel stays alive for the next call.

mathematica_export

Evaluate an expression and write its result to a file.

Example:

{ "name": "mathematica_export", "arguments": { "code": "Plot[Sin[x], {x, 0, 2 Pi}]", "format": "png", "width": 900 } }

Result:

{
  "ok": true,
  "path": "C:\\Users\\you\\AppData\\Local\\Temp\\mathematica-mcp\\mathematica-export-20260101-120000-ab12cd.png",
  "format": "png",
  "width": 900,
  "bytes": 74261,
  "duration_ms": 4100
}

Default artifact directory: %TEMP%\mathematica-mcp on Windows, $TMPDIR/mathematica-mcp on macOS/Linux.

mathematica_kernel_status

• status reports kernel state: running/ready, pid, uptime, call count, detection source, and the candidate-probe results (tried). It never starts a kernel; before first use resolution_attempted is false and candidates lists the paths that will be probed.

• restart kills and respawns the kernel: all in-memory state is lost.

• interrupt is implemented honestly as a restart — a batch math.exe process cannot be reliably interrupted from another thread — and the result says so.

mathematica_information

Returns attributes, context, option count and (possibly truncated) definition for each symbol. Example: {"symbols": ["Plot"]} returns "Attributes" -> "{HoldAll, Protected, ReadProtected}", "Context" -> "System", "OptionsCount" -> 68, and the Options[Plot]` definition. Per-symbol definitions are truncated at 8000 characters to keep tool responses context-friendly.

Configuration

CLI options:

mathematica-mcp [--kernel <path>] [--help] [--version]

There are no other environment variables and no configuration files written by the server.

How it works

• The MCP server reads newline-delimited JSON-RPC frames from stdin and writes responses to stdout. initialize, ping, tools/list, tools/call, resources/list, prompts/list are implemented; unknown methods return -32601, malformed JSON returns -32700.

• On first tool use the server probes kernel candidates (spawn, trivial evaluation, 20 s budget), caches the first working kernel, then starts a long-lived kernel with -noprompt and $CharacterEncoding = "UTF-8". Before every call the cached kernel executable is checked again; if it is gone (or a start attempt fails) the cache is dropped and candidates are re-probed, so a removed Mathematica falls back to an activated Wolfram Engine without a client restart.

• Each evaluation is serialized through a queue (the kernel is single-threaded) and wrapped in one WL Block[...] expression: the user program is passed as a string and evaluated with ToExpression, so syntax errors become ordinary $Failed results (plus ToExpression::sntx* messages) instead of wedging the input parser. Results and messages are returned through length-prefixed WriteString[$Output, ...] frames, which is what keeps multi-line/Unicode results intact.

• A TimeConstrained limit aborts long evaluations; a hard watchdog kills and respawns a kernel that stops responding entirely. stdout is reserved for the MCP protocol — never for kernel chatter.

Security notes

• The server executes arbitrary Wolfram Language code with the privileges of the user running it. Anything the kernel can do, the MCP client can do: read and write files, run RunProcess, make network requests, import/export files, etc. Only connect MCP clients you trust and only evaluate code you trust.

• Files created by mathematica_export are written wherever you ask (or under the OS temp directory). Treat any output path from an untrusted prompt as sensitive.

• The transport is stdio only. Do not expose this server over a network socket; if you need remote access, wrap it in your own authenticated transport.

• Nothing is sent to Wolfram or any cloud service; all evaluation is local. Wolfram licence requirements still apply (see below).

Troubleshooting

No working Mathematica kernel was found / kernel-start errors

The error lists every candidate that was probed and the reason each failed. Point the server at a licensed executable:

setx MATHEMATICA_EXE "C:\Program Files\Wolfram Research\Wolfram\15.0\math.exe"

Check it manually first:

& "C:\Program Files\Wolfram Research\Wolfram\15.0\math.exe" -noprompt
# then type:  2+2   and press Enter twice

No valid password found. / exit code 69

That candidate is an unlicensed Wolfram Engine installation. The server skips it automatically and tries the next candidate. Use a desktop Mathematica math.exe, or activate the Wolfram Engine licence (free Wolfram account → Engine download page → "Activate"). Once an Engine is activated it is used automatically whenever no licensed Mathematica kernel is available.

MathKernel.exe does not respond

Use math.exe instead — it is the documented stdio REPL launcher. The server never selects MathKernel.exe/WolframKernel.exe on Windows for this reason.

evaluation_failed / syntax errors

The code could not be parsed (ToExpression::sntx*). This is an ordinary tool error; the kernel stays usable. Check parentheses/brackets and retry.

timeout errors

The evaluation exceeded timeout_seconds, was aborted, and the kernel is still usable. Raise timeout_seconds for long-running computations. An evaluation that cannot be aborted at all is killed by a hard watchdog and the next call starts a fresh kernel (state is lost).

First PNG/PDF export is slow

The first export in a kernel session initialises the rasterizer (and may install a one-time paclet) and can take several seconds; later exports are fast. The default export timeout is 180 s.

The client reports no tools / server exits immediately

Run node bin/mathematica-mcp.js --help; check stderr (the client usually shows server logs). If node is not on the GUI client's PATH, use an absolute node path in the command. On Windows, prefer forward slashes in JSON paths.

A restart cleared my variables

mathematica_kernel_status {action: "restart"} (and interrupt) drop in-memory state by design; re-run the definitions you need.

Testing

The test suite uses the built-in node:test runner and speaks raw JSON-RPC against the real server:

npm test
# or, without npm:
node --test

The suite includes protocol/JSON-RPC checks, unit tests for kernel detection, and integration tests against a real Mathematica kernel. Kernel integration tests are skipped automatically when no kernel is installed, so the suite is green on CI machines without Mathematica. The same node --test auto-discovery also runs the DSH notebook plugin's tests (under notebook/test/ once the implementation lands).

Vendored copies must stay current (CI checks both):

node dsh/scripts/sync-server.mjs --check
node notebook/scripts/sync-kernel.mjs --check

Force-skip kernel tests (for example in CI):

MATHEMATICA_MCP_TEST_SKIP_KERNEL=1 npm test

Test-only environment variables:

Note: run the runner without a directory argument (node --test), or with explicit files/glob (node --test "test/*.test.js"). On recent Node versions a bare directory argument (node --test test/) is treated as a single test file and fails; node --test auto-discovery works on Node 18+.

License and trademarks

MIT-licensed software; see LICENSE. Using it requires your own licensed Mathematica or free Wolfram Engine — this project does not include, redistribute or sublicense Wolfram software.

Wolfram, Mathematica, Wolfram Language and Wolfram Engine are trademarks of Wolfram Research, Inc. This project is not affiliated with or endorsed by Wolfram Research.

DeepSeek Harness and DSH are part of the DeepSeek Harness project; this project's dsh/ and notebook/ plugins are community integrations.