Mathematica MCP Server

A production-ready Model Context Protocol (MCP) server that executes Mathematica code, built from scratch using Bun, TypeScript, and Zod validation.

Features

• 🚀 Dual Transport Support: HTTP/SSE and stdio transports
• 🔐 Secure Authentication: Bearer token authentication for HTTP transport
• ⏱️ Timeout Control: Configurable execution timeouts with dual protection
• 📝 Multiple Output Formats: text, LaTeX (TeXForm), and Mathematica (InputForm)
• ✅ Type-Safe: Full TypeScript implementation with Zod schema validation
• ⚡ Bun-Powered: Built on Bun for fast performance
• 🛡️ Security: Command injection prevention, timing-safe authentication
• 🔧 Native Package Loading: Load Mathematica packages using standard Needs[] and Get[] syntax

Prerequisites

• Bun (latest version recommended)
• Mathematica with wolframscript in PATH

Installation

1. Navigate to the project directory:

cd mma-mcp

2. Install dependencies:

bun install

3. Configure environment variables (optional):

cp .env.example .env

Edit .env to set your configuration.

Quick Start

Minimal Commands (No .env file required)

# HTTP mode - default port 3000, no authentication
bun run start:http

# HTTP mode - custom port (e.g., 8080)
MCP_HTTP_PORT=8080 bun run start:http

# Stdio mode - for Claude Desktop integration
bun index.ts

HTTP/SSE Mode

# Generate API key and start server
MCP_TRANSPORT=http MCP_API_KEY=$(bun run generate-key) bun start

Server will start on http://127.0.0.1:3000/mcp

Stdio Mode

# Start server with stdio transport
MCP_TRANSPORT=stdio bun start

Available Scripts

bun start              # Start server (uses .env)
bun run start:http     # Start with HTTP transport
bun run start:stdio    # Start with stdio transport
bun run dev            # Development mode with auto-reload
bun test               # Run tests
bun run typecheck      # Type checking
bun run generate-key   # Generate secure API key

Tools

execute_mathematica

Execute Mathematica code with configurable options.

Parameters:

• code (string, required): Mathematica code
• format (string): Output format - text, latex, mathematica (default: text)
• timeout (number): Timeout in seconds (1-86400, default: 300)

Usage Examples:

Basic computation:

{
  "name": "execute_mathematica",
  "arguments": {
    "code": "Solve[x^2 - 5x + 6 == 0, x]"
  }
}

Using LaTeX output format:

{
  "name": "execute_mathematica",
  "arguments": {
    "code": "Integrate[x^2, x]",
    "format": "latex"
  }
}

Loading Mathematica packages:

{
  "name": "execute_mathematica",
  "arguments": {
    "code": "Needs[\"LinearAlgebra`\"]; MatrixPower[{{1,2},{3,4}}, 2]"
  }
}

HTTP API Endpoints

When running in HTTP mode, the server exposes the following endpoints:

GET /health

Comprehensive health check endpoint that verifies all critical server components are operational.

Authentication: None required

Response Status Codes:

• 200 OK - All checks passed, server is fully operational
• 503 Service Unavailable - Server is initializing or one or more checks failed

Response Format:

Healthy Response (200 OK):

{
  "status": "ok",
  "server": "mathematica-mcp-server",
  "version": "1.0.0",
  "timestamp": "2024-01-09T10:30:00.000Z",
  "uptime": 123.45,
  "startedAt": "2024-01-09T10:28:00.000Z",
  "transport": "streamable-http",
  "checks": {
    "wolframScript": true,
    "wolframKernel": true,
    "mcpServer": true,
    "transport": true
  }
}

Unhealthy Response (503 Service Unavailable):

{
  "status": "error",
  "server": "mathematica-mcp-server",
  "version": "1.0.0",
  "timestamp": "2024-01-09T10:30:00.000Z",
  "uptime": 10.5,
  "startedAt": "2

... [View full README on GitHub](https://github.com/wjsoj/mma-mcp#readme)