Connects a locally installed Wolfram kernel (Mathematica or the free Wolfram Engine) to an MCP client, letting agents evaluate Wolfram Language code in a persistent kernel, export expressions to png/svg/pdf/csv/txt/json/tex, check or restart the kernel, and look up symbol attributes and definitions.
Provides tools for evaluating Wolfram Language code in a persistent local kernel with state preserved between calls, plus export of Graphics/Image/data to multiple file formats and symbol information lookups (attributes, context, options, definitions).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mathematica-mcp evaluate the integral of x^2 sin(x) from 0 to pi"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Tool | What it does |
| Evaluate Wolfram Language code in a persistent kernel and return the result ( |
| Evaluate an expression and export it to png / svg / pdf / csv / txt / json / tex; returns the file path and size. |
| Report kernel status, restart it, or interrupt it (interrupt = restart). |
| Look up attributes, context, option count and definitions for Wolfram Language symbols. |
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/ # companion DeepSeek Harness plugin bundle (vendors this server)
├── market/ # DSH plugin-market index for this bundle
└── docs/ # client setup, DSH install, architecture, publishing notesThis 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.
These projects are independent; this one is not affiliated with them.
Related MCP server: CodePier
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.
Node.js ≥ 18 to run the server (no packages to install).
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:
--kernel <path> command-line argument (highest priority),
MATHEMATICA_EXE or MATHEMATICA_KERNEL environment variable,
~/.mathematica-mcp.json with {"kernelPath": "<path>"},
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.
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"git clone https://github.com/yhbcode000/mathematica-mcp.git
cd mathematica-mcp
node bin/mathematica-mcp.js --version # mathematica-mcp 0.1.0
node bin/mathematica-mcp.js --helpThe server speaks MCP on stdin/stdout and is normally started by an MCP client, not by hand.
npx -y mathematica-mcp
# or
npm install -g mathematica-mcp
mathematica-mcp --versionThe npm package is zero-dependency;
npxonly downloads this package itself.
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_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/mcp.json in your project (or the global equivalent):
{
"mcpServers": {
"mathematica": {
"command": "node",
"args": ["D:/tools/mathematica-mcp/bin/mathematica-mcp.js"]
}
}
}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.
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.
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_evaluateEvaluate Wolfram Language code in the persistent kernel.
Parameter | Type | Default | Description |
| string (required) | — | Wolfram Language source. May be multi-line; newline-separated statements are evaluated in order. |
| number |
| Evaluation time limit. On timeout the evaluation is aborted ( |
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_exportEvaluate an expression and write its result to a file.
Parameter | Type | Default | Description |
| string (required) | — | Wolfram Language expression to export (a |
| enum (required) | — |
|
| string | timestamped file under the OS temp dir | Absolute output path (relative paths resolve against the server's CWD). Parent directories are created. |
| number | — | For png/svg/pdf: |
| number | — | For png/svg/pdf: |
| number |
| Export time limit. The first raster/vector export in a kernel session can take several seconds (rasterizer initialisation), hence the generous default. |
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_statusParameter | Type | Default | Description |
| enum |
|
|
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_informationParameter | Type | Description |
| string[] (required) | Symbol names, e.g. |
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.
Setting | How | Notes |
Kernel executable |
| Highest priority; wins over everything below. |
Kernel executable |
| Checked in that order. |
Kernel executable |
| Aliases |
Default evaluate timeout | tool argument | Default 60 s; max 3600 s. |
Default export timeout | tool argument | Default 180 s. |
Artifact location | tool argument | Omit to write under the OS temp dir. |
CLI options:
mathematica-mcp [--kernel <path>] [--help] [--version]There are no other environment variables and no configuration files written by the server.
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".
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.
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).
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 twiceNo 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.
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.
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 --testThe 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:
# Force-skip kernel tests (e.g. in CI):
MATHEMATICA_MCP_TEST_SKIP_KERNEL=1 npm testTest-only environment variables:
Variable | Purpose |
| Skip all kernel integration tests. |
| Use this kernel for integration tests instead of auto-detection. |
| Also used by the tests (normal kernel configuration). |
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+.
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/ bundle is a
community integration.
Evaluate Wolfram Language (Mathematica) code in a persistent local kernel and return the result in InputForm. Variables and function definitions persist between calls. Printed output is captured in "output", and printed messages are listed in "messages". Requires a locally licensed Mathematica or the free Wolfram Engine.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Wolfram Language source code to evaluate, e.g. "2+2", "Plot[Sin[x], {x, 0, 2 Pi}]", or a multi-line program. It is parsed with ToExpression, so newline-separated statements are evaluated in order. | |
| timeout_seconds | No | Maximum evaluation time in seconds (default 60). On timeout the evaluation is aborted and the kernel stays usable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden and does well: it discloses the persistent kernel, that variables and function definitions persist between calls, that printed output goes to 'output', and that messages go to 'messages'. It also states the licensing requirement. It omits some deeper side-effect details (e.g., that arbitrary code execution can mutate kernel state), but covers the key traits beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, followed by concise, high-value details about persistence, output capture, and licensing. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by explaining that results are returned in InputForm and that printed output and messages are captured in named fields. It also states the licensing requirement. Minor gaps remain around timeout abort behavior and error handling, but the core context an agent needs is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters ('code' and 'timeout_seconds') are already fully documented in the schema. The description adds no parameter-specific syntax or behavioral detail beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Evaluate Wolfram Language (Mathematica) code' and specifies the execution context ('persistent local kernel') and return format ('InputForm'). This is concrete enough to distinguish it from sibling tools like export, kernel status, or information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a prerequisite ('Requires a locally licensed Mathematica or the free Wolfram Engine') but does not explicitly say when to use this tool versus alternatives such as mathematica_information or mathematica_export. Usage is implied by the general-purpose evaluation task, leaving the agent to infer boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate Wolfram Language code and export its result to a file on the local machine. Returns the absolute path and byte size of the created file. Useful for plots (png/svg/pdf), tables/data (csv/json/txt) and LaTeX (tex).
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Wolfram Language expression to export, e.g. "Plot[Sin[x], {x, 0, 2 Pi}]" or "Table[{i, i^2}, {i, 10}]". Variables defined by earlier mathematica_evaluate calls can be used. | |
| width | No | For png/svg/pdf: image width in pixels, passed to Mathematica as ImageSize. | |
| format | Yes | Output format. | |
| height | No | For png/svg/pdf: image height in pixels, passed to Mathematica as ImageSize. | |
| file_path | No | Absolute path of the output file. When omitted, a timestamped file is created under the OS temp directory (mathematica-mcp artifacts folder). | |
| timeout_seconds | No | Maximum time for the export in seconds (default 180). The first raster export can take several seconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the key trait: this writes a file to the local machine and returns the absolute path and byte size. It does not say whether an existing file_path is overwritten, whether directories are created, or what permissions or sandbox limits apply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero waste: the action comes first, the return value second, and the format guidance last. Nothing repeats the schema or the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the description covers the return shape, giving the absolute path and byte size of the created file. With six parameters at full schema coverage, the remaining gap is file-overwrite or file-collision semantics, which matter for a tool that writes to disk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented, and the baseline is 3. The description adds only the format-to-use-case mapping, while behaviors like ImageSize, timestamped temp paths, and the 180s default live in the schema rather than the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: evaluate Wolfram Language code and export the result to a file on the local machine. That distinguishes it from mathematica_evaluate, which returns results rather than writing files. It never explicitly names the sibling or says what happens to the evaluated expression itself, so the differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete use cases mapped to formats: plots (png/svg/pdf), tables/data (csv/json/txt), and LaTeX (tex). That is clear context for choosing this tool. It stops short of exclusions, e.g., when to prefer mathematica_evaluate over exporting, or what to do when the expression is non-exportable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return information about Wolfram Language symbols: attributes, context, option count and definitions (for user-defined symbols). Useful for discovering how to use a built-in function such as Plot or Table.
| Name | Required | Description | Default |
|---|---|---|---|
| symbols | Yes | Symbol names to inspect, e.g. ["Plot", "Table", "Integrate"]. Context-qualified names such as "Global`f" are allowed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full disclosure burden. It usefully enumerates returned fields and notes definitions apply to user-defined symbols, implying a read-only inspection, but it does not state behavior for missing symbols, whether evaluation is triggered, or any permission/rate-limit context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the return content and followed by a concrete use case. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter lookup, the description covers what is returned and gives a concrete usage example, while the schema handles input semantics. It lacks detail on output shape and edge cases, but is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single symbols parameter is already fully documented in the schema with examples and context-qualified names. The description adds no additional parameter syntax or constraints beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: return information about Wolfram Language symbols, and enumerates the returned data (attributes, context, option count, definitions). It is substantively distinct from evaluate/export/kernel_status, though it does not name those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear use case: discovering how to use a built-in function such as Plot or Table. It does not state when to prefer alternatives or any exclusions, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the local Mathematica kernel is running (pid, uptime, call count), restart it, or interrupt it. Restarting clears all in-memory state. Interrupt is implemented as a restart because a batch math.exe cannot be reliably interrupted.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | Action to perform (default "status"). | status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does well: it discloses that restart is destructive to in-memory state and that interrupt is silently implemented as a restart due to batch math.exe limitations. That last detail is exactly the kind of non-obvious behavior an agent must know before invoking. It does not say whether the operation requires the kernel to be up, or what happens to concurrent evaluations during a restart.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, both load-bearing: the first states scope and return fields, the second carries the two destructive-behavior caveats. Nothing is redundant and the most consequential warning is not buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately names the status payload fields (pid, uptime, call count). It is nearly complete for a 1-parameter tool; the only gap is what restart/interrupt return and how failures surface, which an agent would still need to discover.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single enum parameter and a documented default, so the schema already establishes the baseline. The description still adds meaning by explaining the consequence of the 'restart' and 'interrupt' values, which the terse schema description does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific resource (local Mathematica kernel) and enumerates the three operations it supports: report status with pid/uptime/call count, restart, and interrupt. That verb-plus-resource specificity makes it clearly distinguishable from siblings like mathematica_evaluate and mathematica_export, which operate on expressions rather than process lifecycle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear what each action does and warns that restart wipes in-memory state, which helps an agent choose between status and restart. It stops short of stating an explicit when-to-use rule (e.g. 'use status to health-check before evaluating, restart after a hung call'), and does not point to any sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0mathematica_evaluatemathematica_exportmathematica_informationmathematica_kernel_statusScored across 4 tools
Each tool has a clearly distinct purpose: evaluating code, exporting results to files, managing/inspecting the kernel process, and querying symbol documentation. There is no overlap between execution, file output, process control, and introspection, so an agent can select unambiguously.
All tools follow a uniform `mathematica_<noun/verb>` snake_case pattern with a consistent server prefix. The verbs (evaluate, export, information) and the noun_status form read predictably and consistently.
Four tools is well-scoped for a Mathematica kernel bridge: evaluation handles nearly all computation, while export, kernel_status, and information cover the few things evaluation cannot do. Each tool earns its place with no redundancy.
The surface covers the core lifecycle: run code, persist state, write results to disk, inspect the kernel, and look up symbols. Minor gaps exist — no tool to read/import existing files back into the kernel or to cleanly shut down the kernel — but these are workable via evaluate or ignored.
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
