@yasogan/math-mcp

$npm version$

A comprehensive Model Context Protocol server that exposes 8 mathematical tools to any MCP-compatible AI agent. Provides arithmetic, symbolic algebra, calculus, matrix operations, statistics, probability distributions, and unit conversions — no code required from the agent side.

Installation
Quick Start
Tool Reference
- evaluate
- solve
- simplify
- factor
- expand
- matrix
- statistics
- units
Expression Syntax Guide
Development

Installation

Using npx (recommended)

No installation required — run directly:

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": ["-y", "@yasogan/math-mcp"]
    }
  }
}

Local installation

npm install -g @yasogan/math-mcp
# or
pnpm add -g @yasogan/math-mcp

Then use directly:

{
  "mcpServers": {
    "math": {
      "command": "@yasogan/math-mcp"
    }
  }
}

Client configuration

| Client | Config Location | | -------------- | ----------------------------------------------------------------- | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | | OpenCode | ~/.opencode/settings.json | | Zed | ~/.config/zed/settings.json | | Cursor | ~/.cursor/settings.json |

Quick Start

Example prompt to an AI agent:

"What's the determinant of a 3x3 matrix [[1,2,3],[4,5,6],[7,8,9]]?"

The agent will call:

matrix({ op: "determinant", a: [[1,2,3],[4,5,6],[7,8,9]] })

→ Returns 0

Tool Reference

evaluate

Purpose: Evaluate mathematical expressions using either numeric (mathjs) or symbolic (Algebrite) computation.

| Parameter | Type | Required | Description | | ------------ | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------- | | expression | string | Yes | The mathematical expression to evaluate | | mode | 'numeric' | 'symbolic' | No | Default: 'numeric' — numeric uses mathjs for floating-point, symbolic uses Algebrite for exact results |

Numeric mode examples:

// Arithmetic
evaluate({ expression: "2^10 + sqrt(144)" }); // → 1036
evaluate({ expression: "factorial(10)" }); // → 3628800
evaluate({ expression: "gcd(48, 18)" }); // → 6

// Trigonometry
evaluate({ expression: "sin(pi/6)" }); // → 0.5
evaluate({ expression: "cos(45 deg)" }); // → 0.70710678
evaluate({ expression: "atan2(1, 1)" }); // → 0.78539816

// Complex numbers
evaluate({ expression: "(2+3i)*(1-i)" }); // → 5+i
evaluate({ expression: "abs(3+4i)" }); // → 5

// Matrices
evaluate({ expression: "det([[1,2],[3,4]])" }); // → -2
evaluate({ expression: "inv([[2,0],[0,4]])" }); // → [[0.5,0],[0,0.25]]

// BigNumber precision
evaluate({ expression: "bignumber(2)^100" }); // → 1.2676506002282294e30 (exact)

// Units
evaluate({ expression: "180 km/h to m/s" }); // → 50 m/s

Symbolic mode examples:

// Derivatives (symbolic)
evaluate({ expression: "diff(x^3 + 2*x, x)", mode: "symbolic" }); // → 3*x^2+2

// Integrals (symbolic)
evaluate({ expression: "integrate(x^2, x)", mode: "symbolic" }); // → 1/3*x^3

// Simplification
evaluate({ expression: "expand((x+1)*(x-1))", mode: "symbolic" }); // → x^2-1

solve

Purpose: Solve algebraic equations for a specified variable. Returns all roots including complex ones.

| Parameter | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------------------------- | | equation | string | Yes | Equation containing exactly one = (e.g., "x^2 - 5x + 6 = 0") | | variable | string | Yes | Variable to solve for (e.g., "x") |

Examples:

// Quadratic equation — returns both roots
solve({ equation: "x^2 - 5x + 6 = 0", variable: "x" });
// → { result: "2, 3", numeric: 2, latex: "x = 2, x = 3" }

// Cubic with complex roots
solve({ equation: "x^3 - 1 = 0", variable: "x" });
// → { result: "1, (-0.5)+(-0.8660254037844386*i), (-0.5)+(0.8660254037844386*i)", ... }

// Find specific root
solve({ equation: "x^2 - 4 = 0", variable: "x" });
// → { result: "2, -2", numeric: 2, latex: "x = 2, x = -2" }

Constraints:

Only polynomial equations supported
Exactly one = required
No inequalities (<, >, <=, >=)

simplify

Purpose: Simplify algebraic expressions using mathematical rules (combine like terms, evaluate constants, apply trig identities).

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------------- | | expression | string | Yes | Expression to simplify |

Examples:

simplify({ expression: "sin(x)^2 + cos(x)^2" }); // → 1
simplify({ expression: "2*x + 3*x" }); // → 5*x
simplify({ expression: "3 + 4 * 2" }); // → 11
simplify({ expression: "(x+1)^2 - (x^2 + 2*x + 1)" }); // → 0
simplify({ expression: "exp(ln(x))" }); // → x

factor

Purpose: Factor polynomial expressions into irreducible components.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------------- | | expression | string | Yes | Expression to factor |

Examples:

factor({ expression: "x^2 - 4" }); // → (x+2)*(x-2)
factor({ expression: "x^3 - 6*x^2 + 11*x - 6" }); // → (x-1)*(x-2)*(x-3)
factor({ expression: "12" }); // → 2^2*3
factor({ expression: "x^2 + 5*x + 6" }); // → (x+2)*(x+3)
factor({ expression: "a^2 - b^2" }); // → (a+b)*(a-b)

expand

Purpose: Expand factored or compound expressions into polynomial form.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------------- | | expression | string | Yes | Expression to expand |

Examples:

expand({ expression: "(x+1)^3" }); // → x^3+3*x^2+3*x+1
expand({ expression: "(a+b)*(a-b)" }); // → a^2-b^2
expand({ expression: "(x+2)*(x-2)" }); // → x^2-4
expand({ expression: "2*(x+y)" }); // → 2*x+2*y

matrix

Purpose: Perform matrix and vector operations.

| Parameter | Type | Required | Description | | --------- | ---------- | -------- | ---------------------------------------------- | | op | string | Yes | Operation name | | a | number[][] | Yes | First matrix/vector | | b | number[][] | No | Second matrix/vector (required for binary ops) |

Supported operations:

| Operation | Description | Requires b? | | -------------- | --------------------------- | ------------- | | multiply | Matrix multiplication A × B | Yes | | add | Matrix addition A + B | Yes | | subtract | Matrix subtraction A - B | Yes | | inverse | Matrix inverse A⁻¹ | No | | transpose | Matrix transpose Aᵀ | No | | determinant | Determinant |A| | No | | eigenvalues | Eigenvalues of A | No | | eigenvectors | Eigenvectors of A | No | | rank | Matrix rank | No | | norm | Frobenius norm ‖A‖ | No | | trace | Matrix trace | No | | dot | Dot product of vectors | Yes | | cross | Cross product of 3D vectors | Yes |

Examples:

// Determinant
matrix({
  op: "determinant",
  a: [
    [1, 2],
    [3, 4],
  ],
});
// → -2

// Inverse
matrix({
  op: "inverse",
  a: [
    [4, 7],
    [2, 6],
  ],
});
// → [[0.6,-0.7],[-0.2,0.4]]

// Eigenvalues
matrix({
  op: "eigenvalues",
  a: [
    [2, 1],
    [1, 2],
  ],
});
// → [3, 1]

// Matrix multiplication
matrix({
  op: "multiply",
  a: [
    [1, 2],
    [3, 4],
  ],
  b: [
    [5, 6],
    [7, 8],
  ],
});
// → [[19,22],[43,50]]

// Dot product
matrix({ op: "dot", a: [[1, 2, 3]], b: [[4, 5, 6]] });
// → 32

// Cross product (3D vectors)
matrix({ op: "cross", a: [[1, 0, 0]], b: [[0, 1, 0]] });
// → [0, 0, 1]

Note: SVD is not supported. Use eigenvalues for similar decomposition.

statistics

Purpose: Descriptive statistics, probability distributions, and linear regression.

| Parameter | Type | Required | Description | | --------- | -------- | ------------- | -------------------------------------------------------------- | | op | string | Yes | Operation name | | data | number[] | Conditional* | Array of numbers (required for descriptive stats & regression) | | args | object | Conditional* | Distribution parameters (required for distributions) |

Descriptive operations (use data):

| Operation | Description | Notes | | ---------- | ------------------------- | ---------------------------------- | | mean | Arithmetic mean | | | median | Median value | | | mode | Most frequent value | Returns first if multiple | | std | Sample standard deviation | Uses n-1 denominator | | variance | Sample variance | Uses n-1 denominator | | min | Minimum value | | | max | Maximum value | | | sum | Sum of all values | | | quantile | Quantile value | Requires args.prob (default 0.5) | | mad | Median absolute deviation | | | skewness | Sample skewness | Requires n ≥ 3 | | kurtosis | Sample kurtosis | Requires n ≥ 4 |

Distribution operations (use args):

| Operation | Parameters | Description | | -------------- | ------------------ | ----------------------- | | normal_pdf | x, mean, std | Probability density | | normal_cdf | x, mean, std | Cumulative distribution | | normal_inv | p, mean, std | Inverse CDF (quantile) | | binomial_pmf | k, n, p | Probability mass | | binomial_cdf | k, n, p | Cumulative distribution | | poisson_pmf | k, lambda | Probability mass | | poisson_cdf | k, lambda | Cumulative distribution | | t_pdf | x, df | Student's t PDF | | t_cdf | x, df | Student's t CDF | | chi2_pdf | x, df | Chi-squared PDF | | chi2_cdf | x, df | Chi-squared CDF |

Regression operations (use data):

| Operation | Description | | ------------------- | -------------------------------------------------------------------- | | linear_regression | Simple linear regression (y = mx + b), x auto-indexed as [0,1,2,...] |

Examples:

// Descriptive statistics
statistics({ op: "mean", data: [4, 8, 15, 16, 23, 42] }); // → 18

// Standard deviation
statistics({ op: "std", data: [2, 4, 4, 4, 5, 5, 7, 9] });
// → 2.138

// Quantile (75th percentile)
statistics({ op: "quantile", data: [1, 2, 3, 4, 5], args: { prob: 0.75 } });
// → 4

// Normal PDF
statistics({
  op: "normal_pdf",
  args: { x: 0, mean: 0, std: 1 },
});
// → 0.398942

// Normal CDF (probability below z-score)
statistics({
  op: "normal_cdf",
  args: { x: 1.96, mean: 0, std: 1 },
});
// → 0.975

// Inverse normal (find z-score for 97.5th percentile)
statistics({
  op: "normal_inv",
  args: { p: 0.975, mean: 0, std: 1 },
});
// → 1.959964

// Binomial probability (exactly 3 heads in 10 flips)
statistics({
  op: "binomial_pmf",
  args: { k: 3, n: 10, p: 0.5 },
});
// → 0.117188

// Poisson (events in time interval)
statistics({
  op: "poisson_pmf",
  args: { k: 3, lambda: 2 },
});
// → 0.180447

// Linear regression
statistics({
  op: "linear_regression",
  data: [2, 4, 6, 8, 10],
});
// → { slope: 2, intercept: 0 }

units

Purpose: Convert between physical units of the same dimension.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------ | | expression | string | Yes | Format: '<value> <unit> to <unit>' |

Supported unit categories:

| Category | Units | | ----------- | ------------------------------------------------------- | | Length | km, m, cm, mm, mi, yards, ft, in, nmi | | Mass | kg, g, mg, lb, oz, ton | | Temperature | degC, degF, K, rank | | Pressure | Pa, kPa, MPa, bar, atm, psi | | Energy | J, kJ, cal, kcal, Wh, kWh | | Speed | m/s, km/h, mph, knots, ft/s | | Area | m2, km2, ha, acre, ft2, mi2 | | Volume | L, mL, gal, qt, pt, cup, fl oz | | Time | s, min, h, day, week, year |

Examples:

units({ expression: "5 km to miles" }); // → 3.10686 miles
units({ expression: "100 degF to degC" }); // → 37.7778 degC
units({ expression: "1 atm to Pa" }); // → 101325 Pa
units({ expression: "60 mph to km/h" }); // → 96.5606 km/h
units({ expression: "1000 kg to lb" }); // → 2204.62 lb
units({ expression: "1 year to days" }); // → 365.242 days

Expression Syntax Guide

Arithmetic Operators

| Symbol | Operation | Example | | ------ | -------------- | ------------- | | + | Addition | 2 + 3 → 5 | | - | Subtraction | 7 - 4 → 3 | | * | Multiplication | 6 * 8 → 48 | | / | Division | 15 / 3 → 5 | | ^ | Exponentiation | 2^10 → 1024 | | % | Modulo | 17 % 5 → 2 |

Functions

sqrt(x); // Square root
abs(x); // Absolute value
log(x); // Natural logarithm
log10(x); // Base-10 logarithm
exp(x); // e^x
factorial(n); // n!
gcd(a, b); // Greatest common divisor
lcm(a, b); // Least common multiple
floor(x); // Round down
ceil(x); // Round up
round(x); // Round to nearest

Trigonometry

(sin(x), cos(x), tan(x)); // Standard functions
(asin(x), acos(x), atan(x)); // Inverses
atan2(y, x); // Two-argument atan
(sinh(x), cosh(x), tanh(x)); // Hyperbolic
(deg, rad); // Unit conversion

Constants

pi; // 3.14159...
e; // 2.71828...
i; // Imaginary unit

Special Values

(Infinity, -Infinity);
NaN;

Development

# Install dependencies
pnpm install

# Build TypeScript
pnpm build

# Run tests
pnpm test

# Run in development (no build required)
pnpm dev

# Run in development with watch
pnpm test:watch

Tech stack: TypeScript, MCP SDK, mathjs, Algebrite, Vitest

License

MIT

MCP Servers

@yasogan/math-mcp

Contents

Installation

Using npx (recommended)

Local installation

Client configuration

Quick Start

Tool Reference

evaluate

solve

simplify

factor

expand

matrix

statistics

units

Expression Syntax Guide

Arithmetic Operators

Functions

Trigonometry

Constants

Special Values

Development

License

Install Package (if required)

Cursor configuration (mcp.json)