@yasogan/math-mcp

<p align="center">

</p>

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.

Contents

• 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