Content
# advanced-math-mcp
MCP (Model Context Protocol) server for advanced mathematics — linear algebra, vector math, symbolic computation, and calculus. Designed for use with Claude and other MCP-compatible LLMs.
## Quick Start
```bash
npm install -g advanced-math-mcp
```
Then add to your MCP client configuration (e.g., `mcp_settings.json`):
```json
{
"mcpServers": {
"advanced-math-mcp": {
"command": "advanced-math-mcp",
"args": [],
"alwaysAllow": [
"evaluate",
"set_variable",
"get_variable",
"list_variables",
"clear_variables",
"matrix_create",
"matrix_identity",
"matrix_zeros",
"matrix_diagonal",
"symbolic_simplify",
"symbolic_substitute",
"symbolic_derivative",
"symbolic_expand",
"symbolic_integrate",
"symbolic_definite_integral",
"symbolic_limit",
"symbolic_partial_derivative"
]
}
}
}
```
## Tools (17 total)
### Unified Expression Evaluator
| Tool | Description |
|---|---|
| `evaluate` | Universal expression evaluator with natural math syntax. Supports matrices, vectors, scalars, decompositions, and custom functions. |
| `set_variable` | Define a named variable (matrix, vector, or scalar) for use in `evaluate` |
| `get_variable` | Retrieve a variable's value |
| `list_variables` | List all defined variables and their types |
| `clear_variables` | Reset all variables |
### Matrix Creation
| Tool | Description |
|---|---|
| `matrix_create` | Create a matrix from a 2D array of strings |
| `matrix_identity` | Create an n×n identity matrix |
| `matrix_zeros` | Create an m×n matrix of zeros |
| `matrix_diagonal` | Create a diagonal matrix from a vector of values |
### Symbolic Math
| Tool | Description |
|---|---|
| `symbolic_simplify` | Simplify algebraic expressions |
| `symbolic_expand` | Expand factored expressions |
| `symbolic_substitute` | Substitute variables with values or expressions |
| `symbolic_derivative` | Compute ordinary derivatives (single-variable) |
| `symbolic_partial_derivative` | Compute partial derivatives (multivariable) |
| `symbolic_integrate` | Compute indefinite integrals (antiderivatives) |
| `symbolic_definite_integral` | Compute definite integrals with bounds |
| `symbolic_limit` | Compute limits of expressions |
## `evaluate` — The Universal Evaluator
All matrix/vector operations use a single `evaluate` tool with natural expression syntax:
### Matrix Operations
```js
// Arithmetic
evaluate("A + B") // addition
evaluate("A - B") // subtraction
evaluate("A * B") // matrix multiplication
evaluate("A ^ 3") // matrix power
// Properties
evaluate("det(A)") // determinant
evaluate("trace(A)") // trace
evaluate("rank(A)") // rank
evaluate("inv(A)") // inverse
evaluate("transpose(A)") // transpose
// Decompositions
evaluate("eig(A)") // eigenvalues & eigenvectors
evaluate("charpoly(A)") // characteristic polynomial (2×2, 3×3)
evaluate("lu(A)") // LU decomposition
evaluate("qr(A)") // QR decomposition
evaluate("svd(A)") // singular value decomposition
// Linear systems
evaluate("solve(A, b)") // solve Ax = b
```
### Vector Operations
```js
evaluate("dot([1,2,3], [4,5,6])") // dot product → 32
evaluate("cross([1,2,3], [4,5,6])") // cross product → [-3, 6, -3]
evaluate("norm([3,4])") // L2 norm → 5
evaluate("norm([3,4], \"1\")") // L1 norm → 7
evaluate("project([3,4], [1,0])") // vector projection → [3, 0]
```
### Inline Literals
```js
evaluate("[[1,2],[3,4]] * [[5,6],[7,8]]") // → [[19,22],[43,50]]
evaluate("det([[4,1],[2,3]])") // → 10
evaluate("inv([[4,7],[2,6]])") // → [[0.6,-0.7],[-0.2,0.4]]
```
### Variable Workflow
```js
set_variable("A", "[[1,2],[3,4]]")
set_variable("B", "[[5,6],[7,8]]")
evaluate("A * B") // uses stored variables
list_variables() // see all defined variables
clear_variables() // reset
```
## Symbolic Math
### Simplification & Expansion
```js
symbolic_simplify("x^2 + 2*x + 1 - (x+1)^2") // → 0
symbolic_expand("(x+1)*(x-1)*(x+2)") // → x^3 + 2x^2 - x - 2
```
### Substitution
```js
// Single variable
symbolic_substitute("x^2 + 2*x", { x: "3" }) // → 15
// Multi-variable
symbolic_substitute("x^2 + y*x + z", { x: "3", y: "2", z: "1" }) // → 16
```
### Calculus
```js
// Derivatives
symbolic_derivative("x^3 + 2*x^2", "x") // → 3x^2 + 4x
symbolic_partial_derivative("x^2*y + sin(z)", "x", 2) // → 2y (second partial)
// Integration
symbolic_integrate("x^2 + sin(x)", "x") // → 0.333x^3 - cos(x) + C
symbolic_definite_integral("x^2", "x", "0", "2") // → 2.667 (∫₀² x² dx)
// Limits
symbolic_limit("sin(x)/x", "x", "0") // → 1
```
## Architecture
```
src/
├── index.ts # Entry point, loads nerdamer plugins
├── server.ts # MCP server setup, tool routing
├── types.ts # Shared types and Zod schemas
├── engine/
│ ├── evaluator.ts # Unified expression evaluator (mathjs + custom functions)
│ ├── symbolic.ts # Symbolic engine (nerdamer + mathjs)
│ ├── math-engine.ts # Low-level matrix operations
│ └── format.ts # Output formatting utilities
└── tools/
├── evaluate.ts # evaluate + variable management tools
├── matrix-create.ts # matrix_create, identity, zeros, diagonal
├── symbolic.ts # symbolic_simplify, substitute, derivative, expand
└── calculus.ts # symbolic_integrate, definite_integral, limit, partial_derivative
```
### Dependencies
| Package | Purpose |
|---|---|
| `@modelcontextprotocol/sdk` | MCP protocol implementation |
| `mathjs` v13 | Numeric matrix operations, expression parsing |
| `nerdamer` | Symbolic algebra, calculus (integrals, limits) |
| `zod` | Runtime input validation |
### Custom Functions in `evaluate`
The evaluator extends mathjs with these custom functions:
| Function | Implementation |
|---|---|
| `rank(A)` | Via eigenvalue count of AᵀA |
| `solve(A, b)` | Wraps `math.lusolve()` |
| `eig(A)` / `eigs(A)` | Wraps `math.eigs()` with formatted output |
| `svd(A)` | Via eigenvalue decomposition of AᵀA |
| `charpoly(A)` | Formula-based for 2×2 and 3×3 |
| `lu(A)` | Alias for `math.lup()` |
| `qr(A)` | Alias for `math.qr()` |
| `project(u, v)` | Vector projection formula |
| `norm(v, type)` | L1, L2 (default), L∞ |
## Development
```bash
git clone https://github.com/PsyWhat/advanced-math-mcp.git
cd advanced-math-mcp
npm install
npm run build # compile TypeScript
npm run dev # watch mode
npm link # install globally for local testing
```
## Testing
```bash
npm test # run all tests (vitest)
npm run test:watch # watch mode
npm run typecheck # TypeScript validation only
```
| Suite | Tests | Coverage |
|---|---|---|
| `evaluator.test.ts` | 36 | Matrix ops, vector ops, decompositions, eigenvalues, variable scope, error handling |
| `symbolic.test.ts` | 15 | Simplify, expand, substitute, ordinary derivatives |
| `calculus.test.ts` | 17 | Indefinite/definite integrals, limits, partial derivatives |
**All 68 tests pass.**
## Known Limitations
- **SVD**: The rank-deficient SVD gives zero vectors for nullspace columns (computed via AᵀA eigen-decomposition, not full Golub-Reinsch)
- **Cholesky**: Not available in mathjs v13; use `lu()` for general decomposition
- **`norm(v, inf)`**: Must use quoted `"inf"` (not bare `inf`) due to mathjs parsing
- **`charpoly`**: Numeric only, supports 2×2 and 3×3 matrices
- **`symbolic_limit`**: Some advanced limits (e.g., `(1+1/x)^x` as `x→∞`) may not fully resolve
## License
MIT
