Math Tools

███╗   ███╗ █████╗ ████████╗██╗  ██╗    ████████╗ ██████╗  ██████╗ ██╗     ███████╗
████╗ ████║██╔══██╗╚══██╔══╝██║  ██║    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
██╔████╔██║███████║   ██║   ███████║       ██║   ██║   ██║██║   ██║██║     ███████╗
██║╚██╔╝██║██╔══██║   ██║   ██╔══██║       ██║   ██║   ██║██║   ██║██║     ╚════██║
██║ ╚═╝ ██║██║  ██║   ██║   ██║  ██║       ██║   ╚██████╔╝╚██████╔╝███████╗███████║
╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝       ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝

A comprehensive Model Context Protocol (MCP) server that provides LLMs with 34+ mathematical tools and a powerful expression evaluator. Transform your AI assistant into a mathematical computation powerhouse with support for everything from basic arithmetic to advanced statistical analysis and data science operations.

🚀 Features

Expression Evaluator

The evaluate tool is the most powerful feature, allowing complex mathematical expressions in a single call:

• Complex Mathematical Expressions: Evaluate sophisticated mathematical expressions
• Function Composition: Chain mathematical functions together seamlessly
• Array Support: Use array notation [1,2,3,4,5] directly in expressions
• Operator Support: Full support for +, -, *, /, ^ (power), % (modulo) operators
• Constants: Built-in mathematical constants (pi, e)
• Precedence Handling: Proper mathematical operator precedence and parentheses support

Professional Error Handling

• Comprehensive input validation with clear, descriptive error messages
• Graceful handling of edge cases (division by zero, empty arrays, etc.)
• Type safety with Zod schema validation

📦 Installation

1. Clone the repository:

   git clone https://github.com/ohqay/math-tools.git
   cd math-tools

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Configure Claude Desktop by adding to your MCP settings:

   {
       "mcpServers": {
           "math": {
               "command": "node",
               "args": ["PATH/TO/PROJECT/math-tools/build/index.js"]
           }
       }
   }

   Replace PATH/TO/PROJECT with the actual path where you cloned the repository.

🔧 Tool Reference

Basic Arithmetic

Tool	Parameters	Description
add	firstNumber, secondNumber	Addition of two numbers
subtract	minuend, subtrahend	Subtraction (minuend - subtrahend)
multiply	firstNumber, secondNumber	Multiplication of two numbers
division	numerator, denominator	Division with zero-check
sum	numbers[]	Sum all numbers in array
modulo	dividend, divisor	Modulo operation (dividend % divisor)
remainder	dividend, divisor	IEEE 754 remainder operation
power	base, exponent	Exponentiation (base^exponent)
sqrt	number	Square root calculation
abs	number	Absolute value

Advanced Mathematics

Tool	Parameters	Description
factorial	n (≥0)	Factorial calculation (n!)
gcd	a, b	Greatest Common Divisor
lcm	a, b	Least Common Multiple
floor	number	Round down to integer
ceiling	number	Round up to integer
round	number	Round to nearest integer

Precision Rounding

Tool	Parameters	Description
roundToPrecision	number, decimalPlaces	Round to N decimal places
floorToPrecision	number, decimalPlaces	Floor to N decimal places
ceilToPrecision	number, decimalPlaces	Ceiling to N decimal places

Statistical Analysis

Tool	Parameters	Description
mean	numbers[]	Arithmetic mean (average)
median	numbers[]	Middle value of sorted dataset
mode	numbers[]	Most frequent value(s)
min	numbers[]	Minimum value
max	numbers[]	Maximum value
variance	numbers[]	Population variance
standardDeviation	numbers[]	Population standard deviation
range	numbers[]	Max - Min difference
percentile	numbers[], p (0-100)	Value at percentile p

Machine Learning & Data Science

Tool	Parameters	Description
correlation	xArray[], yArray[]	Pearson correlation coefficient
covariance	xArray[], yArray[]	Sample covariance
zscore	value, mean, stdDev	Standard score calculation
normalizeArray	numbers[]	Min-max normalization (0-1 scale)
standardizeArray	numbers[]	Z-score standardization

Expression Evaluator

Tool	Parameters	Description
evaluate	expression (string)	Evaluate complex mathematical expressions

Supported in expressions:

• Operators: +, -, *, /, ^ (power), % (modulo)
• Constants: pi, e
• Functions: All 33+ mathematical tools listed above
• Arrays: [1,2,3,4,5] notation for statistical functions
• Parentheses: Full support for grouping and precedence

💡 Usage Examples

Expression Evaluator

The evaluate tool is the most powerful feature, allowing complex mathematical expressions:

// Financial calculations
evaluate('(1 + 0.05)^10 * 10000'); // → Compound interest: $16,288.95

// Statistics with embedded calculations
evaluate('mean([1,2,3,4,5]) + variance([10,20,30,40,50])'); // → Mean + variance

// Advanced mathematical operations
evaluate('factorial(5) + gcd(48, 18) * sqrt(16)'); // → 120 + 6 * 4 = 144

// Machine learning preprocessing
evaluate('correlation([1,2,3,4], [2,4,6,8]) * 100'); // → Perfect correlation: 100

// Complex statistical analysis
evaluate('zscore(85, mean([70,75,80,85,90]), standardDeviation([70,75,80,85,90]))');

// Modulo operations in expressions
evaluate('17 % 5 + power(2, 3)'); // → 2 + 8 = 10
evaluate('(100 % 7) * factorial(3)'); // → 2 * 6 = 12

Individual Tool Usage

Each mathematical operation is also available as a standalone tool:

// Basic arithmetic
add(15, 27); // → 42
multiply(6, 7); // → 42
power(2, 10); // → 1024

// Modulo operations
modulo(17, 5); // → 2 (remainder when 17 is divided by 5)
remainder(17, 5); // → 2 (IEEE 754 remainder operation)
modulo(100, 7); // → 2 (checking divisibility)
modulo(123, 10); // → 3 (extracting last digit)

// Statistical analysis
mean([85, 92, 78, 96, 88]); // → 87.8
standardDeviation([10, 12, 14, 16, 18]); // → 2.83
percentile([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 75); // → 7.75

// Data science operations
normalizeArray([10, 20, 30, 40, 50]); // → [0, 0.25, 0.5, 0.75, 1]
correlation([1, 2, 3, 4, 5], [2, 4, 6, 8, 10]); // → 1 (perfect positive correlation)

🎯 Real-World Applications

Financial Analysis

// Investment growth calculation
evaluate('10000 * (1 + 0.07)^20'); // $38,696.84 after 20 years at 7%

// Risk assessment using standard deviation
standardDeviation([12.5, 15.2, 8.7, 18.9, 11.3]); // Portfolio volatility

Data Science & Analytics

// Correlation analysis
correlation([100, 150, 200, 250, 300], [25, 30, 35, 40, 45]); // → 1.0

// Data preprocessing pipeline
evaluate('mean(normalizeArray([10, 20, 30, 40, 50]))'); // → 0.5

Statistical Research

// Population analysis
evaluate(
    'zscore(175, mean([160, 165, 170, 175, 180]), standardDeviation([160, 165, 170, 175, 180]))'
);

// Percentile calculations for distributions
percentile([45, 52, 58, 61, 66, 72, 78, 83, 89, 95], 90); // → 91.5

Engineering Calculations

// Complex mathematical formulas
evaluate('sqrt(power(3, 2) + power(4, 2))'); // → 5 (Pythagorean theorem)

// Precision engineering
roundToPrecision(3.14159265359, 4); // → 3.1416

Programming & Algorithm Applications

// Checking divisibility
modulo(128, 8); // → 0 (128 is divisible by 8)
modulo(129, 8); // → 1 (129 is not divisible by 8)

// Cycling through values (circular arrays)
evaluate('5 % 3'); // → 2 (index 5 maps to position 2 in 3-element array)
evaluate('(10 + 7) % 12'); // → 5 (hours calculation: 10 AM + 7 hours = 5 PM)

// Hash table indexing
modulo(1337, 101); // → 17 (hash value 1337 maps to bucket 17 in 101-bucket table)

// Digital signal processing
evaluate('modulo(123456, power(10, 3))'); // → 456 (extract last 3 digits)

// Game development (wrapping coordinates)
evaluate('(playerX + moveX) % mapWidth'); // Wrap player position on game map

⚙️ Technical Specifications

• MCP SDK Version: 1.6.0+
• Node.js: ES Modules support required
• TypeScript: Full type safety with Zod validation
• Precision: IEEE 754 double-precision floating point
• Array Size: No arbitrary limits (memory-constrained)
• Expression Complexity: Supports deeply nested expressions
• Error Handling: Comprehensive validation and user-friendly messages

🛡️ Error Handling

Math Tools provides robust error handling for all edge cases:

• Division by zero: Clear error messages for division and modulo operations
• Invalid inputs: Type validation with descriptive feedback
• Empty arrays: Minimum element requirements enforced
• Malformed expressions: Detailed parsing error information
• Numerical overflow: Proper handling of infinite/NaN results
• Array length mismatches: Validation for paired datasets

🚀 Getting Started

1. Install Math Tools using Smithery or manual setup
2. Restart Claude Desktop to load the new MCP server
3. Test with simple operations: Try add(2, 3) or mean([1,2,3,4,5])
4. Explore the expression evaluator: Use evaluate("sqrt(16) + power(2, 3)")
5. Build complex calculations: Combine multiple functions and operations

📝 License

MIT License - feel free to use in your projects!

---

Transform your AI assistant into a mathematical powerhouse with 34+ tools and unlimited expression complexity. 🧮✨