Maxima MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Maxima MCP Server
A production-grade Model Context Protocol server for Maxima, the computer algebra system. It gives LLM clients a stateful symbolic-math workbench: evaluation, calculus, linear algebra, plotting, full-text manual search, and source-code inspection.

┌──────────────┐ stdio / Streamable HTTP ┌──────────────────┐ framed REPL ┌─────────┐
│ MCP client │ ◄─────────────────────────► │ maxima-mcp │ ◄─────────────► │ Maxima │
│ (LLM / IDE) │ │ tools/resources │ │ process │
└──────────────┘ └──────────────────┘ └─────────┘
│
┌────────────┴────────────┐
│ HTML manual + Lisp src │
│ BM25 + symbol indexes │
└─────────────────────────┘Highlights
29 focused tools covering evaluation, algebra, calculus, matrices, plotting, sessions, documentation, share packages and source code.
Persistent sessions with process isolation, per-session queues, idle expiry, LRU eviction, reset and cancellation.
Crash-safe REPL framing using random sentinels, so warnings, errors and multi-line output are attributed to the right statement.
Timeouts that actually stop work: a hung evaluation kills and restarts the process instead of poisoning the server.
Offline documentation index built from the installed
maxima-docHTML manual: 2,800+ symbol entries, BM25 search, examples and categories.Offline source index over
maxima-srcandmaxima-share: symbol → Lisp/Maxima definition, regex search, package discovery.PNG/SVG plotting through Maxima's gnuplot backend, returned as native MCP image content.
Dual transport: stdio for local clients, authenticated Streamable HTTP with health, readiness, Prometheus metrics and CORS.
MCP v2 / 2026-07-28: serves the current protocol revision via per-request envelopes and
server/discover, while keeping sessionful 2025-era Streamable HTTP and stdio support.Hardened defaults: safe mode blocks shell/file primitives, child processes receive a minimal environment, request limits, rate limiting and path traversal protection.
TypeScript, 136 automated tests, ESLint, Prettier, Docker images and CI.
Related MCP server: SageMath MCP Server
Engineering case studies
Three complete worked examples are available:
docs/CASE_STUDY_CANTILEVER.md: preliminary design of a steel cantilever beam, including symbolic ODE derivation, section selection, strength/shear/deflection checks, and Maxima-generated diagrams.
docs/CASE_STUDY_PIPE_LOOP.md: ASME B31.1 thermal expansion loop for a building heating-water riser, including code stress checks, anchor/support loads, an independent 2D frame verification, and a buildable recommendation.
docs/CASE_STUDY_VENTILATION.md: VAV supply-air duct and fan selection for a mid-rise office floor at altitude, including ASHRAE 62.1 ventilation, Colebrook duct friction, ASHRAE 90.1 fan-power compliance, duct heat gain, fan/system operating points and part-load energy.

Enterprise evaluation
docs/REPORT_AI_VS_MAXIMA_MCP.md: enterprise comparison of AI-only problem solving versus AI + Maxima MCP, including technical case results, capability scorecard, risk controls, cost model and rollout plan.
Requirements
Dependency | Notes |
Node.js ≥ 20.19 | Runtime for the MCP server |
Maxima ≥ 5.40 |
|
| Recommended: enables documentation tools and resources |
| Recommended: enables source/package tools |
gnuplot | Required only for |
On Debian/Ubuntu:
sudo apt-get install maxima maxima-doc maxima-src maxima-share gnuplotThe server auto-detects the newest installed Maxima tree under /usr/share/maxima. Both
maxima-doc (HTML) and maxima-src/maxima-share are optional; corresponding tools report a
clear, actionable error when unavailable.
Quick start
From source
git clone https://github.com/nagykamel-egypt/maxima-mcp.git
cd maxima-mcp
npm ci
npm run build
node dist/index.jsThe default transport is stdio, so running it directly waits for an MCP client on stdin/stdout. Logs go to stderr and never pollute the protocol channel.
GitHub release package
Install the tarball directly from the latest release:
npm install -g https://github.com/nagykamel-egypt/maxima-mcp/releases/download/v1.1.0/maxima-mcp-1.1.0.tgz
maxima-mcp --versionOr download maxima-mcp-<version>.tgz and install the local file:
npm install -g ./maxima-mcp-1.1.0.tgzThe release tarball is an npm package that contains the compiled dist/ output.
Docker (HTTP)
docker compose up --build
# or
docker build -t maxima-mcp .
docker run --rm -p 127.0.0.1:7331:7331 \
-e MAXIMA_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
maxima-mcpMCP client configuration
Using an AI CLI? See the AI CLI tutorial for step-by-step setup with OpenCode, Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor CLI, GitHub Copilot CLI, Crush and generic JSON clients.
The examples below assume the release package is installed and
maxima-mcpis onPATH. For a local checkout, use the absolutenode dist/index.jspath instead.
Claude Desktop / Claude Code
claude_desktop_config.json (or the equivalent project .mcp.json):
{
"mcpServers": {
"maxima": {
"command": "maxima-mcp"
}
}
}From a local checkout, use an absolute path:
{
"mcpServers": {
"maxima": {
"command": "node",
"args": ["/absolute/path/to/maxima-mcp/dist/index.js"],
"env": {
"MAXIMA_MCP_DEFAULT_TIMEOUT_MS": "60000"
}
}
}
}VS Code
.vscode/mcp.json:
{
"servers": {
"maxima": {
"type": "stdio",
"command": "maxima-mcp"
}
}
}Cursor
.cursor/mcp.json:
{
"mcpServers": {
"maxima": {
"command": "maxima-mcp"
}
}
}Remote / HTTP
{
"mcpServers": {
"maxima": {
"type": "http",
"url": "http://127.0.0.1:7331/mcp",
"headers": {
"Authorization": "Bearer ${MAXIMA_MCP_AUTH_TOKEN}"
}
}
}
}More examples are in examples/. Ready-to-copy CLI configs are in
examples/cli/, and the full walkthrough is
docs/AI_CLI_TUTORIAL.md.
AI agent skill
A portable, enterprise-oriented agent skill is available at
skills/maxima-mcp/. It gives any MCP-capable client the
tool-selection rules, session discipline, verification protocol, error recovery,
safety controls, deployment guidance, and copy-ready recipes for this server.
# OpenCode (global)
mkdir -p ~/.config/opencode/skills
ln -s "$PWD/skills/maxima-mcp" ~/.config/opencode/skills/maxima-mcp
# Claude Code (project)
mkdir -p .claude/skills
cp -R skills/maxima-mcp .claude/skills/The skill is client-neutral and uses the standard SKILL.md layout. See
skills/maxima-mcp/README.md for installation,
compatibility, validation and smoke tests. The enterprise review report is
docs/SKILL_REVIEW.md.
Tool catalog
Evaluation and sessions
Tool | Purpose |
| Evaluate one expression in a persistent session |
| Evaluate sequential statements, preserving state |
| Create/start a named session |
| Inspect sessions, PIDs, restarts and usage |
| Discard state and restart the process |
| Terminate and remove a session |
Mathematics
Tool | Purpose |
| Symbolic equations and systems, optional floating point |
| Derivatives of arbitrary order |
| Symbolic or numeric ( |
| Two-sided and one-sided limits |
| Taylor expansions |
|
|
| Double or arbitrary-precision |
| Determinant, inverse, rank, trace, eigenvalues, … |
| 2D/3D PNG or SVG plots as MCP images |
Documentation, source and packages
Tool | Purpose |
| Official manual entry for a symbol |
| BM25 search across the manual |
| Example blocks from the manual |
| Discover documented symbols by prefix |
| List manual chapters/sections |
| Read a full manual section |
| Manual categories and counts |
| Find the implementation of a symbol |
| Text/regex search across Lisp and |
| List indexed source files |
| Read a source file |
| List installed share packages |
| Load a share package by exact name |
| Health, version, config limits and index status |
MCP resources
URI | Content |
| Manual table of contents |
| Documentation categories |
| Manual entry for a symbol |
| Full manual section |
| Installed Maxima source file |
MCP prompts
maxima_solve_problem— structured problem-solving workflow.maxima_explain_symbol— grounded explanation using manual + source.maxima_debug_expression— diagnose errors and unexpected results.
Session model
Calls without
session_iduse the default session (defaultby default), which is created lazily.An explicit unknown
session_idis created on first use, subject toMAXIMA_MCP_MAX_SESSIONS.Variables, function definitions and loaded packages persist within a session.
Sessions are serialized internally: concurrent calls to one session queue; calls to different sessions run in parallel.
Idle sessions expire after
MAXIMA_MCP_SESSION_IDLE_MS. When the session limit is reached, the least-recently-used idle session is evicted.A timeout, cancellation, crash or output-limit violation terminates the Maxima process. The next call starts a fresh process; results report
restarted: trueand previously defined state is lost. Usemaxima_session_resetwhen starting unrelated work.
Configuration
All configuration is through environment variables. Invalid values fail fast at startup.
Variable | Default | Description |
|
|
|
|
| Maxima executable |
| — | Extra Maxima CLI arguments ( |
| — | Extra Maxima initialization statements |
|
| Default evaluation timeout |
|
| Hard timeout cap |
|
| Buffer limit before the process is killed |
|
| Per-process RSS ceiling; |
|
| Per-statement retained output |
|
| Maximum expression length |
|
| Maximum statements per batch |
|
| Maximum rendered image size |
|
| Concurrent sessions (processes) |
|
| Idle session expiry |
|
| Default session id |
|
| Allow |
|
| Persistent userdir for compiled packages |
|
| Cache directory |
|
| Enable documentation tools |
|
| Build doc/source indexes in background at startup |
|
| HTML manual directory |
| auto-detected | Maxima Lisp source directory |
| auto-detected | Maxima share directory |
|
| Search result cap |
|
| Source file content cache budget ( |
|
|
|
|
|
|
|
| HTTP bind address |
|
| HTTP port |
| — | Bearer token for |
|
| Comma-separated allowed origins |
| loopback | Comma-separated allowed |
|
| Requests per window per IP ( |
|
| Rate-limit window |
|
| HTTP request body limit |
|
| Return JSON instead of SSE streams |
|
| Trust |
|
| Idle MCP HTTP session expiry |
See .env.example for a copyable template.
HTTP transport
Start with:
MAXIMA_MCP_TRANSPORT=http \
MAXIMA_MCP_HOST=127.0.0.1 \
MAXIMA_MCP_PORT=7331 \
MAXIMA_MCP_AUTH_TOKEN=change-me \
node dist/index.jsEndpoint | Auth | Purpose |
| Bearer | Streamable HTTP MCP endpoint |
| no | Liveness |
| no | Readiness (Maxima available) |
| Bearer* | Prometheus metrics |
| no | Server metadata |
* Bearer authentication is enforced on /metrics only when MAXIMA_MCP_AUTH_TOKEN is set.
Metrics include tool calls, tool latency, evaluation counts/latency, open sessions and busy sessions in Prometheus text format.
Security
Safe mode is on by default and blocks system, run, load, save, writefile, read,
eval_string, :lisp, gnuplot output/preamble options and similar primitives. Dedicated tools
(maxima_package_load, maxima_plot) provide vetted alternatives.
Safe mode is a defense-in-depth measure, not a sandbox. Maxima is a Turing-complete language and the MCP server executes expressions by design. If you accept untrusted users, run the server in a container/VM with no credentials, a read-only filesystem where possible, and CPU/memory limits. The child Maxima process receives a minimal environment (no bearer tokens or cloud credentials).
See docs/SECURITY.md for the full threat model and deployment checklist.
Development
npm ci
npm run typecheck
npm run lint
npm test
npm run buildUseful scripts:
Script | Description |
| Run with |
| Unit tests only |
| Tests against real Maxima, docs, source and gnuplot |
| Prettier |
| Compile to |
Integration tests automatically skip when Maxima, maxima-doc, maxima-src or gnuplot are not
installed.
Repository layout:
src/
index.ts CLI entrypoint (stdio/http)
server.ts MCP server factory + instructions
http.ts Streamable HTTP, auth, health, metrics, sessions
runtime.ts Shared runtime (sessions, docs, source, metrics)
config.ts Zod-validated environment configuration
maxima/ process framing, sessions, output, plotting
docs/ HTML manual index, BM25 search, source index
tools/ tool registrations by domain
resources.ts MCP resources
prompts.ts MCP prompts
test/
unit/ pure logic
integration/ real Maxima / docs / source / HTTPSee docs/ARCHITECTURE.md for internals.
Troubleshooting
Symptom | Fix |
| Install Maxima or set |
Docs tools return | Install |
Source tools return | Install |
| Raise |
Plot fails | Install gnuplot and verify |
First | Share packages may compile on first use; the persistent userdir caches artifacts |
HTTP 403 | Add the host to |
HTTP 401 | Set the |
More detail in docs/TROUBLESHOOTING.md.
License
MIT — see LICENSE.
Maxima itself is distributed under the GNU GPL; this project only invokes it as a separate process.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Scientific compute for AI agents: symbolic, numerical, quantum, chemistry, ODE. Paid via x402.
Exact arithmetic, algebra, calculus, physics, chemistry and finance with a checkable formula.
Integrates Wolfram Language and Wolfram|Alpha accessing curated data and sophisticated algorithms.
Unofficial Math.js MCP — wraps the mathjs.org API (free, no auth)
Related MCP Servers
- FlicenseAqualityDmaintenanceAllows LLMs to execute Wolfram Language code in a secure, session-based environment by providing an interface to interact with a Wolfram Mathematica kernel.34-
- AlicenseBqualityAmaintenanceA universal mathematics MCP server that gives LLM clients full access to SageMath for symbolic calculus, number theory, linear algebra, and more, with persistent state across tool calls.4020MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Maxima, a computer algebra system, for symbolic mathematics computation.4MIT
- AlicenseNot gradedqualityCmaintenanceExposes the full SageMath computer algebra system to LLM clients through MCP tools for symbolic mathematics, solving, calculus, plotting, and number theory.73 npm1Creative Commons Zero v1.0 Universal