Mathematica MCP Server

This repository contains a Model Context Protocol (MCP) server that allows MCP clients (like Cursor) to execute Mathematica code via wolframscript and verify mathematical derivations.

Overview

This server acts as a bridge, enabling applications that support MCP to leverage the power of a local Mathematica installation for tasks such as:

• Performing complex mathematical calculations.
• Verifying mathematical derivation steps provided by humans or AI models.
• Generating LaTeX or Mathematica string representations of expressions.

Prerequisites

• Mathematica must be installed on your system.
• The wolframscript command-line utility must be available in your system's PATH. You can test this by running wolframscript -help in your terminal.
• Node.js (Recommended: v16 or later, as inferred from tsconfig.json target ES2022).

Installation

1. Clone the repository:

   git clone <repository-url>
   cd <repository-directory>

2. Install dependencies:

   npm install

3. Build the server:

   npm run build

   This command compiles the TypeScript source code from src/ into JavaScript in the build/ directory and makes the main script executable.

Running the Server

To start the MCP server, run the following command in your terminal:

node build/index.js

The server will start and listen for connections from MCP clients via standard input/output (stdio). Keep this terminal window open while you intend to use the server.

For more robust deployments, consider using a process manager like pm2 to run the server in the background and manage restarts.

Integration with MCP Clients (e.g., Cursor, Cline, Claude Desktop)

MCP clients generally discover and communicate with running MCP servers. The exact configuration steps can vary depending on the client application.

General Steps:

1. Start the Mathematica MCP Server: Ensure the server is running in a terminal:

   node build/index.js

2. Configure Your MCP Client: Add the server to your client's configuration. This often involves editing a JSON settings file. See client-specific instructions below.
3. Restart Your MCP Client: After starting the server or changing configuration, restart your client application to ensure it detects the Mathematica server.

Client-Specific Configuration:

• Cline: According to the Cline MCP Server Development Protocol, you typically configure servers in a settings file (often settings.json within the Cline configuration directory). You would add an entry like this:

  {
    "mcpServers": {
      "mathematica-server": {
        "command": "node",
        "args": ["/full/path/to/mcp-server-mathematica/build/index.js"], // Replace with the actual absolute path
        "disabled": false,
        "autoApprove": [] // Optional: Add tool names to auto-approve
      }
      // ... other servers ...
    }
  }

  Replace /full/path/to/mcp-server-mathematica/build/index.js with the absolute path to the built index.js file on your system.

• Cursor: Cursor might require editing a specific settings file, potentially like ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (though this path might change). The structure would be similar to the Cline example above.

• Other Clients (e.g., Claude Desktop): Consult the documentation for your specific MCP client. Look for sections on "MCP Servers," "Tool Configuration," or "External Tools." The configuration generally involves specifying the command (node), the path to the server script (build/index.js), and potentially environment variables if needed.

Available Tools

The server exposes the following tools to MCP clients:

1. execute_mathematica

Executes arbitrary Mathematica code and returns the result.

Input Schema:

{
  type: "object",
  properties: {
    code: {
      type: "string",
      description: "Mathematica code to execute"
    },
    format: {
      type: "string",
      description: "Output format (text, latex, or mathematica)",
      enum: ["text", "latex", "mathematica"],
      default: "text"
    }
  },
  required: ["code"]
}

Example Usage (Client Request):

• Natural Language: "Calculate the integral of x^2 from 0 to 1 using Mathematica and format as LaTeX"
• Direct Tool Call:

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

2. verify_derivation

Verifies a sequence of mathematical expressions to check if each step logically follows from the previous one using Simplify[prev == current].

Input Schema:

{
  type: "object",
  properties: {
    steps: {
      type: "array",
      description: "Array of mathematical expressions (as strings) representing steps in a derivation. Requires at least two steps.",
      items: {
        type: "string"
      }
    },
    format: {
      type: "string",
      description: "Output format for the verification report (text, latex, or mathematica)",
      enum: ["text", "latex", "mathematica"],
      default: "text"
    }
  },
  required: ["steps"]
}

Example Usage (Client Request):

• Natural Language: "Verify this derivation: ['x^2 - y^2', '(x-y)(x+y)']"
• Direct Tool Call:

  {
    "tool_name": "verify_derivation",
    "arguments": {
      "steps": [
        "x^2 - y^2",
        "(x-y)*(x+y)"
      ],
      "format": "text"
    }
  }

Troubleshooting

• Server Not Found/Not Responding:
  • Ensure the server is running in a terminal (node build/index.js).
  • Check if wolframscript is installed and accessible in your PATH (wolframscript -help).
  • Restart your MCP client application.
  • Check the client's MCP configuration.
• Tool Errors:
  • Check the server's terminal output (stderr) for logs and error messages from wolframscript.
  • Verify the syntax of the Mathematica code or steps provided.
  • Ensure the steps array for verify_derivation has at least two elements.
• Mathematica Issues: Ensure your Mathematica installation is licensed and working correctly.

Project Structure

• src/: TypeScript source code for the server.
• build/: Compiled JavaScript output (generated by npm run build).
• package.json: Project metadata and dependencies.
• tsconfig.json: TypeScript compiler configuration.